The OCI referrers API lets you ask a registry which artifacts point to a given image digest. A signature, an SBOM or an attestation is stored as its own manifest with a subject field naming the image it describes. A single request then lists them, so tools find them without guessing tag names.
The problem it solves
An image is identified by a digest. A signature or SBOM about that image is a separate object. How do you find it later?
An older approach used a tag convention: derive a tag name from the image digest and store the extra object under it. That works but clutters tag lists, and it is awkward to list or filter.
The distribution specification adds a cleaner link. A manifest can include a subject field, which the spec describes as an association from one manifest to another, typically used to attach an artifact to an image.
How a lookup works
The endpoint, from the distribution specification, is a GET on the repository path with referrers and the digest of the subject manifest.
- The response is an image index listing manifests that refer to that digest.
- If nothing matches, the list is empty.
- A registry that supports the API must not return a 404 for referrers requests. Invalid digest syntax returns a 400.
- You can filter by artifact type with a query parameter. When a filter is applied, the response carries a header saying so.
If a registry does not support the API, the client must fall back to the tag schema. In that scheme the tag is the algorithm name, a hyphen and the encoded hash, for example sha256 followed by the hash. So the same data can be found either way, depending on the registry.
Why it matters for supply chain checks
A deployment check that wants "a signature from my build identity, plus an SBOM" needs to find both for the digest being deployed. With referrers, the verifier asks once and filters by type. Without it, each tool invents its own convention.
It also keeps the link tied to the digest, not a tag. Move a tag and the referrers of the old digest do not follow, which is the behavior you want.
Things to check in your registry
- Does it support the API? If not, clients fall back to tags, which can behave differently.
- Are referrers deleted with the image? Clean-up policies may remove an image but leave its attached artifacts, or the reverse.
- Who can push referrers? Pushing an artifact that points at your image is a write operation. Restrict it. Anyone who can attach a manifest can add something your tools might list.
- Do your tools verify the signer, not only that something is attached?
- Copying images between registries. Make sure your copy tool also copies referrers, or the signature stays behind.
A caution about trust
The presence of a referrer proves only that someone pushed it. An attached SBOM is not trustworthy until you verify its signature and signer. Treat the API as discovery, and the signature check as trust. See what a signature proves.
Verify digests as you pull
The specification also tells clients to verify content. When the reference is a digest, clients should check that the returned manifest matches it, and blob bodies should match the requested digest. Use clients that do this, and pull by digest where you can.
Safeguard's SBOM and dependency scanning produces SBOMs you can keep alongside your images, and policies and gates can use them. Try a free scan.
Quick check
Is a referrer the same as a tag?
No. A tag is a movable name. A referrer is linked through the subject field to a specific digest.
Can the API tell me the signature is valid?
No. It lists what is attached. Validity comes from verifying the signature.
Sources
Last reviewed: 19 October 2026.
