The OCI referrers API lets a registry list artifacts that point at an image by digest, such as signatures and SBOMs. A client calls GET /v2/NAME/referrers/DIGEST and gets an index of manifests whose subject matches. If the call returns 404, clients fall back to a tag schema.
What problem it solves
An image digest is the stable identity of an image. Signatures, SBOMs and attestations should be found by that digest, not by naming conventions. The OCI distribution spec defines a subject field, an association from one manifest to another that is typically used to attach an artifact to an image.
How it works
| Piece | Behavior per the spec |
|---|---|
| Endpoint | GET /v2/NAME/referrers/DIGEST |
| Filter | Optional artifactType query parameter |
| Response | An image index of manifests with a matching subject |
| No matches | An empty list |
| Push order | A registry must accept a manifest whose subject is not yet present |
| Unsupported | Client must fall back to the referrers tag schema |
The fallback tag is built from the subject digest, with the algorithm and encoded value joined by a hyphen, and the tag holds an image index matching the API response.
Why security teams care
If you verify that every deployed image has a signature and an SBOM, you need a reliable way to list what is attached. Without the API, tooling may rely on tag naming that anyone with push rights could imitate. With it, discovery follows the digest.
What to check in your registry
- Does it support the referrers API, or only the fallback?
- Can you restrict who may push referrers to a repository? Anyone who can push can attach artifacts to a digest, so treat the list as untrusted until verified.
- Do your verification tools query by artifactType and then verify signatures, not just presence?
- Does copying an image to another registry keep its referrers? Test it, since this post did not confirm tool behavior.
The key rule
Presence is not proof. A referrer listed for a digest is a lead. A verified signature from an expected identity is evidence. For more on that distinction, see what a container image signature proves and does not.
Try it yourself
Try it yourself
Click through it at your own pace, or open it full screen. Look at which artifacts and metadata hang off a scanned image and ask which of them you could verify.
Quick check
Is the referrers API required for signing to work?
Not necessarily. The spec provides a fallback tag schema, so clients can work with registries that lack the API.
Who can add a referrer to my image?
Anyone with push access to the repository. Restrict that access and verify signatures rather than trusting the list.
Safeguard asset discovery and container image scanning give you an inventory of the images you run.
Sources
Last reviewed: 19 October 2026.
