atproto

Install

opam update && opam install atproto

Then (libraries atproto) in dune. OCaml >= 4.14.1 and < 5.4 (CI: 4.14.1 and 5.3.0). Jetstream dict-zstd needs system libzstd (libzstd-dev / Homebrew zstd). Pin the GitHub repo or a local clone for an unreleased tip.

Quick start

These two calls need the public network, not ATP_AUTH. Identity.resolve_handle talks to the entryway (ATP_HOST, default bsky.social). Feed.search_posts talks to the public AppView (public.api.bsky.app). ATP_PUBLIC only gates tests, not this snippet.

let did = (Identity.resolve_handle "jay.bsky.team").did
let posts = Feed.search_posts ~q:"atproto" ~limit:5 ()

Where to go next

• Resolve a handle or DID: Atproto.Identity
• App-password session: Atproto.Session and Atproto.Auth
• Profiles and timelines: Atproto.Feed and Atproto.Actor
• Write a post or follow: Atproto.Records and Atproto.Repo
• Firehose / Jetstream: Atproto.Firehose and Atproto.Jetstream
• Browser login: Atproto.Oauth. You host client-metadata.json. DPoP cannot be proxied.
• Hosted chat or video: Atproto.Chat and Atproto.Video

Modules

Identity. Handle and DID resolve, PLC, did:web / did:key.

• Atproto.Identity
• Atproto.Did_plc
• Atproto.Did_web
• Atproto.Did_key

Session. App passwords, invites, email, getServiceAuth.

• Atproto.Auth
• Atproto.Session
• Atproto.Server

AppView. Profiles, timelines, search, graphs, bookmarks, public labelers.

• Atproto.Actor
• Atproto.Feed
• Atproto.Graph
• Atproto.Bookmark
• Atproto.Labeler
• Atproto.Unspecced

Records. create/put/delete/applyWrites and typed post / like / follow builders.

• Atproto.Repo
• Atproto.Records
• Atproto.Embed
• Atproto.Facet

Firehose. subscribeRepos and Jetstream live tail / archive HTTP.

• Atproto.Firehose
• Atproto.Websocket
• Atproto.Jetstream

OAuth. PKCE, DPoP, public HTTPS client-metadata, browser login. You still host the metadata document. Authed AppView / Ozone / chat use Oauth.get_service_auth, not the DPoP access token.

• Atproto.Oauth
• Atproto.Oauth_scope

Hosted clients. Chat (api.bsky.chat; extra DM scopes), video (video.bsky.app; no transcoder), contacts (no SMS gateway), registerPush (caller gateway).

• Atproto.Chat
• Atproto.Video
• Atproto.Contact
• Atproto.Notification

Ozone and reports.

• Atproto.Ozone
• Atproto.Admin
• Atproto.Temp
• Atproto.Moderation

Sync and indexer. Repo CAR, MST, CID. Atproto.Repo_sync is a backfill toolkit, not a Tap host.

• Atproto.Sync
• Atproto.Repo_sync
• Atproto.Mst
• Atproto.Cid
• Atproto.Car
• Atproto.Dag_cbor

Protocol bits. at://, TIDs, XRPC, lexicons, labels, HTTP.

• Atproto.At_uri AT URI scheme (at://) — public records (AT URI spec) and experimental permissioned space URIs from proposal 0016.
• Atproto.Tid
• Atproto.Syntax
• Atproto.Xrpc
• Atproto.Error
• Atproto.Lexicon
• Atproto.Label
• Atproto.Http_client

Also Atproto.Draft, Atproto.Ageassurance, Atproto.Site, Atproto.Germnetwork, Atproto.App, Atproto.Client, Atproto.Request, and Atproto.Response.

Experimental proposal 0016 (At_uri.Space plus the modules below). Not a spaces product API. No space host in this package.

• Atproto.Lt_hash
• Atproto.Space_commit
• Atproto.Space_credential
• Atproto.Space_xrpc
• Atproto.Space_sync

Notes

Live public-network tests skip unless ATP_PUBLIC=1. Default opam install -t / @runtest stay offline.

Official lexicons are pinned at f0d4877a.

Atproto.Chat needs a DM grant (transition:chat.bsky or include:chat.bsky.authFullChatClient, or a privileged app-password). Atproto.Jetstream archive HTTP needs an operator JETSTREAM_API_KEY; live subscribe stays unauthenticated. Space helpers skip unless ATP_SPACE=1 and ATP_SPACE_HOST names a real host.