How would you query a registry's HTTP API v2 directly with curl to see which manifest a tag currently resolves to and whether a given layer blob exists, and when is doing that worth the trouble?

## Why go under the CLI The CLI collapses a multi-step HTTP conversation into one line and one error message. When something misbehaves — an intermittent 403, a mirror serving stale content, a proxy mangling headers, a tag that seems to have moved — talking to the API directly tells you exactly which step fails and what the server actually said. It also lets you read image metadata without transferring layers, which is valuable when the image is large or the environment is bandwidth-constrained. ## Step 1: the token Every request needs authorization. Probe the base endpoint and read the challenge: ``` curl -sI https://registry.example.com/v2/ Www-Authenticate: Bearer realm="https://auth.example.com/token",service="registry.example.com" ``` Then exchange credentials for a scoped token: ``` curl -s -u "$USER:$SECRET" \ "https://auth.example.com/token?service=registry.example.com&scope=repository:team/app:pull" ``` The JSON contains `token`. Anonymous access to a public repository works with no `-u`. If this step fails, the problem is authentication; if it succeeds and the registry still refuses, the problem is authorization — that split alone resolves a large share of registry tickets. ## Step 2: the manifest, and the `Accept` header ``` curl -s -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/vnd.oci.image.index.v1+json" \ -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \ -H "Accept: application/vnd.oci.image.manifest.v1+json" \ -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ -D headers.txt \ https://registry.example.com/v2/team/app/manifests/1.2 ``` Content negotiation is real here: the registry serves whichever supported type you accept, and a request without these headers can get a legacy schema or an error. Two response shapes: - **An index / manifest list** — `manifests[]` entries each with a `digest`, `size` and `platform` (`os`, `architecture`, sometimes `variant`). This is a multi-platform image; fetch the entry for the platform you care about **by digest** using the same endpoint. - **An image manifest** — a `config` descriptor and an ordered `layers[]` array, each with `mediaType`, `size` and `digest`. The response header `Docker-Content-Digest` is the digest of the manifest the tag currently resolves to. That is the value you record when you need to prove what was deployed, and comparing it across two registries or two moments in time answers "did this tag change?". `HEAD` on the same URL returns the headers only — the cheapest way to ask "does this tag exist and what does it point to?". ## Step 3: config and blobs The config blob is small and contains the interesting metadata: ``` curl -s -H "Authorization: Bearer $TOKEN" \ https://registry.example.com/v2/team/app/blobs/sha256:<config-digest> | jq '.config.Env, .history' ``` That gives environment variables, entrypoint, exposed ports, labels, the `diff_ids` of the uncompressed layers and the build history — all without pulling the image. For layers, `HEAD /v2/<repo>/blobs/<digest>` answers existence with `200` plus `Content-Length`, or `404`. Note that a blob `GET` commonly returns `307` to object storage with a pre-signed URL; follow redirects with `-L`, and **do not** forward the `Authorization` header to the redirect target (curl does not by default across hosts, which is the correct behaviour — the signed URL carries its own auth and leaking a bearer token to a storage host is a real incident class). ## Other useful endpoints - `GET /v2/` — API version check and the auth challenge; a 200 means "registry reachable and I am authorized at base level". - `GET /v2/<repo>/tags/list` — tags in a repository, paginated with `?n=` and a `Link` header. - `GET /v2/_catalog` — repository listing; usually restricted or disabled on shared registries because it is an enumeration surface. - `DELETE /v2/<repo>/manifests/<digest>` — deletes by digest, never by tag, and only when the registry has deletion enabled; the space returns after garbage collection. ## When it earns its keep - An ambiguous pull failure: you can see precisely whether the 401 came from the token service or the registry, and whether the manifest or a blob is missing. - Verifying a mirror or pull-through cache has the same digest for a tag as the upstream. - Confirming a promotion actually moved the digest you approved. - Reading labels, entrypoint or base-image metadata for an image you are not allowed to (or do not want to) run. - Diagnosing corporate proxies that strip `WWW-Authenticate`, rewrite `Accept`, or break the redirect to blob storage. Modern tooling (`crane`, `skopeo`, `oras` and friends) wraps these calls, and reaching for them is entirely legitimate — but knowing the underlying requests is what lets you interpret their output and debug the cases they do not cover.