ATProto Records and Provenance

In AT Protocol, a record is a schema-defined data object published in a repository owned by an account. ATProto records include posts, profiles, bookmarks, annotations, and other application data.

ATProto gives each record several identifiers because a useful reference may need to answer three different questions:

1. Where is the record?
2. Who published it?
3. Which exact version was observed?

This page is part of the AT Protocol section of this wiki. It explains how AT URIs, DIDs, CIDs, repositories, and Lexicons answer those questions, and which identifiers an ATProto application should preserve when it links to a record.

One record, two kinds of identity

A public ATProto record has an address called an AT URI. It looks like this:

at://did:plc:example/app.example.bookmark/3abc

You do not need to memorize the syntax. It has three useful parts:

• did:plc:example identifies the account that owns the record;
• app.example.bookmark identifies the type of record;
• 3abc identifies this particular record within that type.

The first part is a DID, or decentralized identifier. A DID is the stable identity behind an ATProto account. Handles can change, and an account can move to another Personal Data Server, but the DID remains the record's authority.

The complete AT URI is the record's logical address. An author can edit the record without changing that address.

That is where the second identifier becomes useful. A CID, or content identifier, is a fingerprint of the record's exact encoded contents. Change the contents and the CID changes.

The distinction is similar to a document URL and a checksum:

• the AT URI tells you which document you mean;
• the CID tells you which version of that document you saw.

What happens after an edit

Imagine a bookmark record with this description:

A clear introduction to distributed social networking.

Its address might remain:

at://did:plc:example/app.example.bookmark/3abc

If the author later changes the description, the AT URI stays the same. The CID changes because the record's contents changed.

This gives applications a choice. They can follow the AT URI to whatever the record says now, or they can preserve the CID when the exact earlier version matters.

ATProto's standard strong reference stores both:

{
  "uri": "at://did:plc:example/app.example.bookmark/3abc",
  "cid": "bafy..."
}

The URI identifies the record. The CID records the version that was observed when the reference was created.

Where the record lives

Each ATProto account has a repository containing its public records. The account's DID document tells the network which Personal Data Server currently hosts that repository.

The repository is a verifiable key/value store. Record addresses are the keys; CIDs point to the current values. The repository publishes signed commits that anchor its current state. A proof through the repository's Merkle tree can connect a record path and CID to that signed state.

This is what makes a copied record inspectable. A consumer does not have to trust the server that handed it the bytes. It can verify the content against the CID and verify the repository path against the account's signed state.

How the record gets its shape

A Lexicon is ATProto's schema format. It describes which fields a record may contain and what types those fields use.

For example, a bookmark Lexicon might require a URL and creation time while allowing an optional description. The record's $type field names the Lexicon that describes it.

Lexicons make records understandable across applications. They establish shape, not truth. A valid record can still contain a false claim, a broken URL, or a judgment another application rejects.

Which reference should you keep?

Use an AT URI by itself when you want the current version of a record. A profile link or a live collection entry often works this way.

Use an AT URI and CID together when the exact version matters. Common examples include:

• a reply to a particular post;
• an annotation quoting a passage;
• a moderation or approval decision;
• a research note that should remain reproducible;
• an audit log explaining what a system acted on.

Use a CID by itself only when you care about exact bytes independently of their publisher and repository address. You will still need another way to find those bytes and explain what they represent.

What provenance does not prove

These identifiers can show who published a record, where it lived, and which version was referenced. They cannot prove that its claims are correct or that another community has accepted it.

Those are separate decisions. A forum may publish an ATProto admission wrapper saying that a member's post belongs in one of its categories. A reviewer may approve one CID but not later edits at the same URI, which creates the problem described in Approving Mutable ATProto Records.

The practical rule is simple: preserve the address when identity matters, preserve the fingerprint when version matters, and preserve both when another decision depends on what was actually seen.