AT Protocol (atproto)
A guide for building on atproto -- the protocol behind Bluesky and the broader atmosphere of interoperable apps. This file is the overview and a router; deep details live in references/.
Mental model
atproto is a federated protocol where users own a signed, content-addressed data repository that any service can replicate. Apps are mostly app views -- services that consume the network firehose, validate records against a Lexicon schema, index them, and expose a read API. Writes go to the user's PDS via XRPC.
Five concepts to keep in your head:
- DIDs identify accounts permanently (
did:plc:... or did:web:...).
- Handles are mutable, DNS-based usernames.
- Repositories are signed, content-addressed Merkle Search Trees of records held on a PDS.
- Lexicons are JSON schemas naming and validating records and HTTP endpoints, addressed by NSID (
com.example.fooBar).
- XRPC is HTTP transport for Lexicon-defined endpoints; the firehose is the WebSocket variant.
Service roles
Real systems are made of four roles. An app you build is usually #3.
- PDS (Personal Data Server) -- hosts a user's repo, signing keys, blobs. Authenticates clients. One per user.
- Relay -- subscribes to many PDSes' firehoses and aggregates into one stream. Optimisation, not source of truth.
- App View -- subscribes to a relay, validates records, indexes them, exposes XRPC reads. Bluesky's timeline service is one. A "feed generator" is a thin specialised app view.
- Labeler -- emits signed labels (moderation/badge metadata) on URIs. Has its own DID and signing key.
What to read next
This SKILL.md is intentionally thin. For anything beyond a high-level question, jump to the right reference:
| You are doing |
Read |
| Authoring a Lexicon (records, queries, procedures, subscriptions) |
references/lexicon.md |
| Lexicon style guide -- naming, conventions, design patterns |
references/lexicon-style.md |
| Working with DIDs, handles, AT URIs, NSIDs, TIDs, record keys |
references/identity.md |
| Calling XRPC endpoints, handling errors, auth, proxying |
references/xrpc.md |
| Reading repos, commits, MSTs, CAR files, the data model |
references/repository.md |
Consuming the firehose / subscribeRepos, event framing |
references/firehose.md |
| OAuth client implementation specifics |
references/oauth.md |
| Designing an app view end-to-end (the most common task) |
references/app-view.md |
| Picking a Go package from indigo, code sketches |
references/indigo-go.md |
If a question spans several topics, start with app-view.md -- it stitches the others together.
Default stack for Markus's Go projects
- Identity, syntax, repo, lexicon, XRPC, OAuth: the indigo Go SDK (
github.com/bluesky-social/indigo). See references/indigo-go.md.
- Indexing storage: SQLite or Postgres. Persist the firehose cursor in the same database.
- Serving HTML: gomponents + Datastar, per the existing fabrik skills.
The most common gotchas
These bite people the first time they build anything on atproto:
- Handles are not durable. Always store DIDs as the primary identifier; cache handles separately and refresh on
#identity events.
- Lexicons can never tighten or loosen constraints after publication. Add optional fields only; mint a new NSID for breaking changes.
- Floats are not in the data model. Use integers, or strings for fixed-point.
$type is required on records, blobs, and union variants. Strict clients silently drop records without it.- TID timestamps are advisory. Use your own
indexedAt for ordering.
- EXIF stripping on uploaded blobs is the client's job, not the PDS's.
- Bidirectional verification is mandatory when resolving handles -- handle->DID, then DID->handle. Otherwise anyone can claim any handle.
Spec index
https://atproto.com/specs/atp -- starting point for everything below.
Worked examples: Statusphere tutorial (TS), indigo services (Go), Bluesky's canonical Lexicons (the best style reference).
1---2name: atproto3description: Guide for building on the AT Protocol (the "atmosphere") -- authoring Lexicons, building app views, consuming the firehose, working with identity (DIDs, handles), repositories, records, XRPC endpoints, and OAuth. Use this skill whenever the user is building anything on atproto/Bluesky/the atmosphere -- writing Lexicon JSON, calling com.atproto.* or app.bsky.* endpoints, parsing AT URIs (`at://...`), DIDs (`did:plc:...`, `did:web:...`), handles, TIDs, the indigo Go SDK (`github.com/bluesky-social/indigo`), the firehose / `subscribeRepos`, MSTs, CAR files, DAG-CBOR/DRISL, app views, feed generators, labelers, or PDS interactions. Triggers even if the user doesn't say "atproto" -- words like "lexicon", "PDS", "app view", "firehose", "did:plc", or `at://` URIs are enough.4license: MIT5---67# AT Protocol (atproto)89A guide for building on atproto -- the protocol behind Bluesky and the broader atmosphere of interoperable apps. This file is the overview and a router; deep details live in `references/`.1011## Mental model1213atproto is a federated protocol where users own a signed, content-addressed data **repository** that any service can replicate. Apps are mostly **app views** -- services that consume the network firehose, validate records against a **Lexicon** schema, index them, and expose a read API. Writes go to the user's PDS via XRPC.1415Five concepts to keep in your head:1617- **DIDs** identify accounts permanently (`did:plc:...` or `did:web:...`).18- **Handles** are mutable, DNS-based usernames.19- **Repositories** are signed, content-addressed Merkle Search Trees of records held on a **PDS**.20- **Lexicons** are JSON schemas naming and validating records and HTTP endpoints, addressed by **NSID** (`com.example.fooBar`).21- **XRPC** is HTTP transport for Lexicon-defined endpoints; the firehose is the WebSocket variant.2223## Service roles2425Real systems are made of four roles. An app you build is usually #3.26271. **PDS (Personal Data Server)** -- hosts a user's repo, signing keys, blobs. Authenticates clients. One per user.282. **Relay** -- subscribes to many PDSes' firehoses and aggregates into one stream. Optimisation, not source of truth.293. **App View** -- subscribes to a relay, validates records, indexes them, exposes XRPC reads. Bluesky's timeline service is one. A "feed generator" is a thin specialised app view.304. **Labeler** -- emits signed labels (moderation/badge metadata) on URIs. Has its own DID and signing key.3132## What to read next3334This SKILL.md is intentionally thin. For anything beyond a high-level question, jump to the right reference:3536| You are doing | Read |37|---|---|38| Authoring a Lexicon (records, queries, procedures, subscriptions) | [`references/lexicon.md`](references/lexicon.md) |39| Lexicon style guide -- naming, conventions, design patterns | [`references/lexicon-style.md`](references/lexicon-style.md) |40| Working with DIDs, handles, AT URIs, NSIDs, TIDs, record keys | [`references/identity.md`](references/identity.md) |41| Calling XRPC endpoints, handling errors, auth, proxying | [`references/xrpc.md`](references/xrpc.md) |42| Reading repos, commits, MSTs, CAR files, the data model | [`references/repository.md`](references/repository.md) |43| Consuming the firehose / `subscribeRepos`, event framing | [`references/firehose.md`](references/firehose.md) |44| OAuth client implementation specifics | [`references/oauth.md`](references/oauth.md) |45| Designing an app view end-to-end (the most common task) | [`references/app-view.md`](references/app-view.md) |46| Picking a Go package from indigo, code sketches | [`references/indigo-go.md`](references/indigo-go.md) |4748If a question spans several topics, start with `app-view.md` -- it stitches the others together.4950## Default stack for Markus's Go projects5152- **Identity, syntax, repo, lexicon, XRPC, OAuth**: the indigo Go SDK (`github.com/bluesky-social/indigo`). See `references/indigo-go.md`.53- **Indexing storage**: SQLite or Postgres. Persist the firehose cursor in the same database.54- **Serving HTML**: gomponents + Datastar, per the existing fabrik skills.5556## The most common gotchas5758These bite people the first time they build anything on atproto:5960- **Handles are not durable.** Always store DIDs as the primary identifier; cache handles separately and refresh on `#identity` events.61- **Lexicons can never tighten or loosen constraints after publication.** Add optional fields only; mint a new NSID for breaking changes.62- **Floats are not in the data model.** Use integers, or strings for fixed-point.63- **`$type` is required** on records, blobs, and union variants. Strict clients silently drop records without it.64- **TID timestamps are advisory.** Use your own `indexedAt` for ordering.65- **EXIF stripping on uploaded blobs is the client's job**, not the PDS's.66- **Bidirectional verification is mandatory** when resolving handles -- handle->DID, then DID->handle. Otherwise anyone can claim any handle.6768## Spec index6970<https://atproto.com/specs/atp> -- starting point for everything below.7172| Spec | URL |73|---|---|74| Lexicon | <https://atproto.com/specs/lexicon> |75| Data model | <https://atproto.com/specs/data-model> |76| Repository | <https://atproto.com/specs/repository> |77| XRPC | <https://atproto.com/specs/xrpc> |78| Sync / firehose | <https://atproto.com/specs/sync> |79| Event stream framing | <https://atproto.com/specs/event-stream> |80| OAuth | <https://atproto.com/specs/oauth> |81| DIDs | <https://atproto.com/specs/did> |82| Handles | <https://atproto.com/specs/handle> |83| NSIDs | <https://atproto.com/specs/nsid> |84| TIDs | <https://atproto.com/specs/tid> |85| Record keys | <https://atproto.com/specs/record-key> |86| AT URI | <https://atproto.com/specs/at-uri-scheme> |87| Blobs | <https://atproto.com/specs/blob> |88| Labels | <https://atproto.com/specs/label> |89| Cryptography | <https://atproto.com/specs/cryptography> |90| Permissions | <https://atproto.com/specs/permission> |91| Accounts | <https://atproto.com/specs/account> |9293Worked examples: [Statusphere tutorial](https://atproto.com/guides/statusphere-tutorial) (TS), [indigo](https://github.com/bluesky-social/indigo) services (Go), [Bluesky's canonical Lexicons](https://github.com/bluesky-social/atproto/tree/main/lexicons) (the best style reference).
maragudk