Guides
Task-oriented documentation. If you are looking for the signature of a particular method, you want the API reference instead.
New here? Start with Quickstart, then Concepts.
Start here
DIDs, handles, records, lexicons and NSIDs: the vocabulary behind every method name.
App passwords, two-factor login, session reuse, and automatic token refresh.
The two clients, what differs between them, and running calls concurrently.
Doing things on Bluesky
Text, rich text, replies, images, video, embeds, and link cards.
Timelines, threads, profiles, and paging through a cursor.
Likes, reposts, follows, mutes, blocks, lists, and starter packs.
Reading notifications, unread counts, and polling for new ones.
Conversations, messages, and reactions, on a separate service the client proxies to.
Working with the protocol
Past the convenience methods: namespaces, record sugar, and raw repository operations.
NSID aliases, building models, DotDict, unknown types, and the record registry.
Handles, DIDs, NSIDs, AT-URIs, TIDs, and how to turn on strict validation.
Resolving handles and DIDs, DID documents, and caching the results.
Streaming the network
Every event on the network, signed and verifiable, as CAR-encoded commits.
The same events as plain JSON, filtered server-side, plus archive replay.
Configuration and operations
The exception hierarchy, what maps to which status code, timeouts, and rate limits.
Routing requests to another service, accepting labelers, and what clone() shares.
Configuring httpx: timeouts, retries, proxies, and the low-level invoke methods.
Building something bigger
A complete service, end to end: firehose ingest, the skeleton endpoint, service auth, and publishing the feed.
Generate typed models and a working client from lexicons of your own.