Share feedback
Answers are generated based on the documentation.
Product manualDownload OpenAPI specificationMarkdown

Check existence of blob

HEAD/v2/{name}/blobs/{digest}

Check whether a blob (layer or config) exists in the registry.

This is useful before uploading a blob to avoid duplicates.

If the blob is present, the registry returns a 200 OK response with headers like Content-Length and Docker-Content-Digest.

If the blob does not exist, the response will be 404 Not Found.

Connection and access

API connection and authentication guidance

https://registry-1.docker.io — Docker Hub registry API

Use one of these alternatives. Requirements within an alternative apply together.

  • registryToken

Parameters

name path Required

Name of the Repository

Type: string

All schema constraints and annotations
{
  "type": "string"
}

digest path Required

Digest of the blob

Type: string

All schema constraints and annotations
{
  "type": "string"
}

Request and responses

Response 200

Blob exists

No response content is declared.

Headers

Content-Length

Size of the blob in bytes

{
  "description": "Size of the blob in bytes",
  "example": 32654,
  "schema": {
    "type": "integer"
  }
}
Content-Type

MIME type of the blob content

{
  "description": "MIME type of the blob content",
  "example": "application/octet-stream",
  "schema": {
    "type": "string"
  }
}
Docker-Content-Digest

Digest of the blob

{
  "description": "Digest of the blob",
  "example": "sha256:abc123def4567890...",
  "schema": {
    "type": "string"
  }
}

Response 401

Authentication required

No response content is declared.

Response 403

Access denied

No response content is declared.

Response 404

Blob not found

No response content is declared.

Response 429

Too many requests

No response content is declared.

Referenced schemas

Complete operation contract
{
  "description": "Check whether a blob (layer or config) exists in the registry.\n\nThis is useful before uploading a blob to avoid duplicates.\n\nIf the blob is present, the registry returns a `200 OK` response with headers like `Content-Length` and `Docker-Content-Digest`.\n\nIf the blob does not exist, the response will be `404 Not Found`.\n",
  "operationId": "CheckBlobExists",
  "parameters": [
    {
      "description": "Name of the Repository",
      "example": "library/ubuntu",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Digest of the blob",
      "example": "sha256:abc123def4567890...",
      "in": "path",
      "name": "digest",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Blob exists",
      "headers": {
        "Content-Length": {
          "description": "Size of the blob in bytes",
          "example": 32654,
          "schema": {
            "type": "integer"
          }
        },
        "Content-Type": {
          "description": "MIME type of the blob content",
          "example": "application/octet-stream",
          "schema": {
            "type": "string"
          }
        },
        "Docker-Content-Digest": {
          "description": "Digest of the blob",
          "example": "sha256:abc123def4567890...",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required"
    },
    "403": {
      "description": "Access denied"
    },
    "404": {
      "description": "Blob not found"
    },
    "429": {
      "description": "Too many requests"
    }
  },
  "summary": "Check existence of blob",
  "tags": [
    "Blobs"
  ],
  "x-codeSamples": [
    {
      "label": "cURL",
      "lang": "Bash",
      "source": "# HEAD to check if a blob exists\ncurl -I \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  https://registry-1.docker.io/v2/library/ubuntu/blobs/sha256:abc123...\n"
    }
  ]
}