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

Check if manifest exists

HEAD/v2/{name}/manifests/{reference}

Use this endpoint to verify whether a manifest exists by tag or digest.

This is a lightweight operation that returns only headers (no body). It is useful for:

  • Checking for the existence of a specific image version
  • Determining the digest or size of a manifest before downloading or deleting

This endpoint requires authentication with pull scope.

Use the Accept header to select the manifest representation. Supported media types:

  • application/vnd.docker.distribution.manifest.v2+json
  • application/vnd.docker.distribution.manifest.list.v2+json
  • application/vnd.oci.image.manifest.v1+json
  • application/vnd.oci.image.index.v1+json

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"
}

reference path Required

Tag or digest to check

Type: string

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

Request and responses

Response 200

Manifest exists.

No response content is declared.

Headers

Content-Length

Size of the manifest in bytes

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

Media type of the manifest

{
  "description": "Media type of the manifest",
  "example": "application/vnd.docker.distribution.manifest.v2+json",
  "schema": {
    "type": "string"
  }
}
Docker-Content-Digest

Digest of the manifest

{
  "description": "Digest of the manifest",
  "example": "sha256:abc123...",
  "schema": {
    "type": "string"
  }
}

Response 401

Authentication required.

No response content is declared.

Response 403

Access denied.

No response content is declared.

Response 404

Manifest not found.

No response content is declared.

Response 429

Too many requests.

No response content is declared.

Referenced schemas

Complete operation contract
{
  "description": "Use this endpoint to verify whether a manifest exists by tag or digest.\n\nThis is a lightweight operation that returns only headers (no body). It is useful for:\n- Checking for the existence of a specific image version\n- Determining the digest or size of a manifest before downloading or deleting\n\nThis endpoint requires authentication with pull scope.\n\nUse the `Accept` header to select the manifest representation. Supported media types:\n\n- `application/vnd.docker.distribution.manifest.v2+json`\n- `application/vnd.docker.distribution.manifest.list.v2+json`\n- `application/vnd.oci.image.manifest.v1+json`\n- `application/vnd.oci.image.index.v1+json`\n",
  "operationId": "HeadImageManifest",
  "parameters": [
    {
      "description": "Name of the Repository",
      "example": "library/ubuntu",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Tag or digest to check",
      "examples": {
        "by-digest": {
          "summary": "Digest",
          "value": "sha256:abc123def456..."
        },
        "by-tag": {
          "summary": "Tag",
          "value": "latest"
        }
      },
      "in": "path",
      "name": "reference",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Manifest exists.",
      "headers": {
        "Content-Length": {
          "description": "Size of the manifest in bytes",
          "example": 7082,
          "schema": {
            "type": "integer"
          }
        },
        "Content-Type": {
          "description": "Media type of the manifest",
          "example": "application/vnd.docker.distribution.manifest.v2+json",
          "schema": {
            "type": "string"
          }
        },
        "Docker-Content-Digest": {
          "description": "Digest of the manifest",
          "example": "sha256:abc123...",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required."
    },
    "403": {
      "description": "Access denied."
    },
    "404": {
      "description": "Manifest not found."
    },
    "429": {
      "description": "Too many requests."
    }
  },
  "summary": "Check if manifest exists",
  "tags": [
    "Manifests"
  ],
  "x-codeSamples": [
    {
      "label": "cURL",
      "lang": "Bash",
      "source": "# HEAD /v2/{name}/manifests/{reference}\ncurl -I \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Accept: application/vnd.docker.distribution.manifest.v2+json\" \\\n  https://registry-1.docker.io/v2/library/ubuntu/manifests/latest\n"
    }
  ]
}