Methods
Every method the server serves: each lexicon in spec/lexicons that defines one, as PDS.md says. Each is an XRPC method, an MCP tool and a pds command at once, named as COMMANDS.md says; a method with no tool answers or takes something other than JSON. This page is made from the lexicons, and the page linked under each method says what it does.
app.bsky.actor
Section titled “app.bsky.actor”app.bsky.actor.getPreferences
Section titled “app.bsky.actor.getPreferences”Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.
- XRPC
- GET
/xrpc/app.bsky.actor.getPreferences - CLI
pds actor get-preferences- MCP
actor_get_preferences- Specified in
- Proxying, service auth and preferences · lexicon
Output
| Name | Type | Description |
|---|---|---|
preferences | app.bsky.actor.defs#preferences |
app.bsky.actor.getProfile
Section titled “app.bsky.actor.getProfile”Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.
- XRPC
- GET
/xrpc/app.bsky.actor.getProfile - CLI
pds actor get-profile- MCP
actor_get_profile- Output
app.bsky.actor.defs#profileViewDetailed- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
actor | string (at-identifier) | Handle or DID of account to fetch profile of. |
app.bsky.actor.getProfiles
Section titled “app.bsky.actor.getProfiles”Get detailed profile views of multiple actors.
- XRPC
- GET
/xrpc/app.bsky.actor.getProfiles - CLI
pds actor get-profiles- MCP
actor_get_profiles- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
actors | array of string (at-identifier), at most 25 |
Output
| Name | Type | Description |
|---|---|---|
profiles | array of app.bsky.actor.defs#profileViewDetailed |
app.bsky.actor.putPreferences
Section titled “app.bsky.actor.putPreferences”Set the private preferences attached to the account.
- XRPC
- POST
/xrpc/app.bsky.actor.putPreferences - CLI
pds actor put-preferences- MCP
actor_put_preferences- Specified in
- Proxying, service auth and preferences · lexicon
Input
| Name | Type | Description |
|---|---|---|
preferences | app.bsky.actor.defs#preferences |
app.bsky.feed
Section titled “app.bsky.feed”app.bsky.feed.getActorLikes
Section titled “app.bsky.feed.getActorLikes”Get a list of posts liked by an actor. Requires auth, actor must be the requesting account.
- XRPC
- GET
/xrpc/app.bsky.feed.getActorLikes - CLI
pds feed get-actor-likes- MCP
feed_get_actor_likes- Errors
BlockedActorBlockedByActor- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
actor | string (at-identifier) | |
limit | integer, 1 to 100, default 50, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
feed | array of app.bsky.feed.defs#feedViewPost |
app.bsky.feed.getAuthorFeed
Section titled “app.bsky.feed.getAuthorFeed”Get a view of an actor’s ‘author feed’ (post and reposts by the author). Does not require auth.
- XRPC
- GET
/xrpc/app.bsky.feed.getAuthorFeed - CLI
pds feed get-author-feed- MCP
feed_get_author_feed- Errors
BlockedActorBlockedByActor- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
actor | string (at-identifier) | |
limit | integer, 1 to 100, default 50, optional | |
cursor | string, optional | |
filter | string, posts_with_replies, posts_no_replies, posts_with_media, posts_and_author_threads, posts_with_video, default "posts_with_replies", optional | Combinations of post/repost types to include in response. |
includePins | boolean, default false, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
feed | array of app.bsky.feed.defs#feedViewPost |
app.bsky.feed.getFeed
Section titled “app.bsky.feed.getFeed”Get a hydrated feed from an actor’s selected feed generator. Implemented by App View.
- XRPC
- GET
/xrpc/app.bsky.feed.getFeed - CLI
pds feed get-feed- MCP
feed_get_feed- Errors
UnknownFeed- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
feed | string (at-uri) | |
limit | integer, 1 to 100, default 50, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
feed | array of app.bsky.feed.defs#feedViewPost |
app.bsky.feed.getPostThread
Section titled “app.bsky.feed.getPostThread”Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.
- XRPC
- GET
/xrpc/app.bsky.feed.getPostThread - CLI
pds feed get-post-thread- MCP
feed_get_post_thread- Errors
NotFound- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | Reference (AT-URI) to post record. |
depth | integer, 0 to 1000, default 6, optional | How many levels of reply depth should be included in response. |
parentHeight | integer, 0 to 1000, default 80, optional | How many levels of parent (and grandparent, etc) post to include. |
Output
| Name | Type | Description |
|---|---|---|
thread | one of app.bsky.feed.defs#threadViewPost, app.bsky.feed.defs#notFoundPost, app.bsky.feed.defs#blockedPost | |
threadgate | app.bsky.feed.defs#threadgateView, optional |
app.bsky.feed.getTimeline
Section titled “app.bsky.feed.getTimeline”Get a view of the requesting account’s home timeline. This is expected to be some form of reverse-chronological feed.
- XRPC
- GET
/xrpc/app.bsky.feed.getTimeline - CLI
pds feed get-timeline- MCP
feed_get_timeline- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
algorithm | string, optional | Variant ‘algorithm’ for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism. |
limit | integer, 1 to 100, default 50, optional | |
cursor | string, optional | |
since | string, optional | Return only items newer than the position identified by this cursor value, newest first. Use the startCursor from a previous response. The item at that position is not returned because the caller already holds it. When the bounded range is exhausted, the returned cursor equals this value so that pagination continues below the boundary. |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
startCursor | string, optional | Cursor identifying the newest item in this page. Pass it as since on a later request to fetch only newer content. |
feed | array of app.bsky.feed.defs#feedViewPost |
app.bsky.notification
Section titled “app.bsky.notification”app.bsky.notification.registerPush
Section titled “app.bsky.notification.registerPush”Register to receive push notifications, via a specified service, for the requesting account. Requires auth.
- XRPC
- POST
/xrpc/app.bsky.notification.registerPush - CLI
pds notification register-push- MCP
notification_register_push- Specified in
- Proxying, service auth and preferences · lexicon
Input
| Name | Type | Description |
|---|---|---|
serviceDid | string (did) | |
token | string | |
platform | string, ios, android, web | |
appId | string | |
ageRestricted | boolean, optional | Set to true when the actor is age restricted |
app.bsky.notification.unregisterPush
Section titled “app.bsky.notification.unregisterPush”The inverse of registerPush - inform a specified service that push notifications should no longer be sent to the given token for the requesting account. Requires auth.
- XRPC
- POST
/xrpc/app.bsky.notification.unregisterPush - CLI
pds notification unregister-push- MCP
notification_unregister_push- Specified in
- Proxying, service auth and preferences · lexicon
Input
| Name | Type | Description |
|---|---|---|
serviceDid | string (did) | |
token | string | |
platform | string, ios, android, web | |
appId | string |
com.atproto.admin
Section titled “com.atproto.admin”com.atproto.admin.getSubjectStatus
Section titled “com.atproto.admin.getSubjectStatus”Get the service-specific admin status of a subject (account, record, or blob).
- XRPC
- GET
/xrpc/com.atproto.admin.getSubjectStatus - CLI
pds admin get-subject-status- MCP
admin_get_subject_status- Specified in
- Account lifecycle · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did), optional | |
uri | string (at-uri), optional | |
blob | string (cid), optional |
Output
| Name | Type | Description |
|---|---|---|
subject | one of com.atproto.admin.defs#repoRef, com.atproto.repo.strongRef, com.atproto.admin.defs#repoBlobRef | |
takedown | com.atproto.admin.defs#statusAttr, optional | |
deactivated | com.atproto.admin.defs#statusAttr, optional |
com.atproto.admin.updateSubjectStatus
Section titled “com.atproto.admin.updateSubjectStatus”Update the service-specific admin status of a subject (account, record, or blob).
- XRPC
- POST
/xrpc/com.atproto.admin.updateSubjectStatus - CLI
pds admin update-subject-status- MCP
admin_update_subject_status- Specified in
- Account lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
subject | one of com.atproto.admin.defs#repoRef, com.atproto.repo.strongRef, com.atproto.admin.defs#repoBlobRef | |
takedown | com.atproto.admin.defs#statusAttr, optional | |
deactivated | com.atproto.admin.defs#statusAttr, optional |
Output
| Name | Type | Description |
|---|---|---|
subject | one of com.atproto.admin.defs#repoRef, com.atproto.repo.strongRef, com.atproto.admin.defs#repoBlobRef | |
takedown | com.atproto.admin.defs#statusAttr, optional |
com.atproto.identity
Section titled “com.atproto.identity”com.atproto.identity.getRecommendedDidCredentials
Section titled “com.atproto.identity.getRecommendedDidCredentials”Describe the credentials that should be included in the DID doc of an account that is migrating to this service.
- XRPC
- GET
/xrpc/com.atproto.identity.getRecommendedDidCredentials - CLI
pds identity get-recommended-did-credentials- MCP
identity_get_recommended_did_credentials- Specified in
- Identity · lexicon
Output
| Name | Type | Description |
|---|---|---|
rotationKeys | array of string, optional | Recommended rotation keys for PLC dids. Should be undefined (or ignored) for did:webs. |
alsoKnownAs | array of string, optional | |
verificationMethods | unknown, optional | |
services | unknown, optional |
com.atproto.identity.requestPlcOperationSignature
Section titled “com.atproto.identity.requestPlcOperationSignature”Request an email with a code to in order to request a signed PLC operation. Requires Auth.
- XRPC
- POST
/xrpc/com.atproto.identity.requestPlcOperationSignature - CLI
pds identity request-plc-operation-signature- MCP
identity_request_plc_operation_signature- Specified in
- Moving an account between servers · lexicon
com.atproto.identity.resolveHandle
Section titled “com.atproto.identity.resolveHandle”Resolves an atproto handle (hostname) to a DID. Does not necessarily bi-directionally verify against the the DID document.
- XRPC
- GET
/xrpc/com.atproto.identity.resolveHandle - CLI
pds identity resolve-handle- MCP
identity_resolve_handle- Errors
HandleNotFound- Specified in
- Identity · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
handle | string (handle) | The handle to resolve. |
Output
| Name | Type | Description |
|---|---|---|
did | string (did) |
com.atproto.identity.signPlcOperation
Section titled “com.atproto.identity.signPlcOperation”Signs a PLC operation to update some value(s) in the requesting DID’s document.
- XRPC
- POST
/xrpc/com.atproto.identity.signPlcOperation - CLI
pds identity sign-plc-operation- MCP
identity_sign_plc_operation- Specified in
- Moving an account between servers · lexicon
Input
| Name | Type | Description |
|---|---|---|
token | string, optional | A token received through com.atproto.identity.requestPlcOperationSignature |
rotationKeys | array of string, optional | |
alsoKnownAs | array of string, optional | |
verificationMethods | unknown, optional | |
services | unknown, optional |
Output
| Name | Type | Description |
|---|---|---|
operation | unknown | A signed DID PLC operation. |
com.atproto.identity.submitPlcOperation
Section titled “com.atproto.identity.submitPlcOperation”Validates a PLC operation to ensure that it doesn’t violate a service’s constraints or get the identity into a bad state, then submits it to the PLC registry
- XRPC
- POST
/xrpc/com.atproto.identity.submitPlcOperation - CLI
pds identity submit-plc-operation- MCP
identity_submit_plc_operation- Specified in
- Moving an account between servers · lexicon
Input
| Name | Type | Description |
|---|---|---|
operation | unknown |
com.atproto.identity.updateHandle
Section titled “com.atproto.identity.updateHandle”Updates the current account’s handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.
- XRPC
- POST
/xrpc/com.atproto.identity.updateHandle - CLI
pds identity update-handle- MCP
identity_update_handle- Specified in
- Identity · lexicon
Input
| Name | Type | Description |
|---|---|---|
handle | string (handle) | The new handle. |
com.atproto.memberspace
Section titled “com.atproto.memberspace”com.atproto.memberspace.listMembers
Section titled “com.atproto.memberspace.listMembers”List the members of a space with a memberspace policy. Requires auth as the space authority, implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.memberspace.listMembers - CLI
pds memberspace list-members- MCP
memberspace_list_members- Errors
SpaceNotFoundNotAuthorizedPolicyMismatchInvalidCursor- Specified in
- Spaces: policies and the space lifecycle · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
limit | integer, 1 to 1000, default 100, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
members | array of com.atproto.memberspace.defs#member |
com.atproto.memberspace.putMembers
Section titled “com.atproto.memberspace.putMembers”Add members to a space, or update existing members’ access, in a single commit. Requires auth as the space authority, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.memberspace.putMembers - CLI
pds memberspace put-members- MCP
memberspace_put_members- Errors
SpaceNotFoundNotAuthorizedPolicyMismatch- Specified in
- Spaces: policies and the space lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
members | array of com.atproto.memberspace.defs#member, at most 100 |
com.atproto.memberspace.removeMembers
Section titled “com.atproto.memberspace.removeMembers”Remove members from a space in a single commit. DIDs that are not members are ignored. Requires auth as the space authority, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.memberspace.removeMembers - CLI
pds memberspace remove-members- MCP
memberspace_remove_members- Errors
SpaceNotFoundNotAuthorizedPolicyMismatch- Specified in
- Spaces: policies and the space lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
dids | array of string (did), at most 100 |
com.atproto.repo
Section titled “com.atproto.repo”com.atproto.repo.applyWrites
Section titled “com.atproto.repo.applyWrites”Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.repo.applyWrites - CLI
pds repo apply-writes- MCP
repo_apply_writes- Errors
InvalidSwap- Specified in
- The repository's records · lexicon
Input
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo (aka, current account). |
validate | boolean, optional | Can be set to ‘false’ to skip Lexicon schema validation of record data across all operations, ‘true’ to require it, or leave unset to validate only for known Lexicons. |
writes | array of one of create, update, delete | |
swapCommit | string (cid), optional | If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations. |
Output
| Name | Type | Description |
|---|---|---|
commit | com.atproto.repo.defs#commitMeta, optional | |
results | array of one of createResult, updateResult, deleteResult, optional |
com.atproto.repo.createRecord
Section titled “com.atproto.repo.createRecord”Create a single new repository record. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.repo.createRecord - CLI
pds repo create-record- MCP
repo_create_record- Errors
InvalidSwap- Specified in
- The repository's records · lexicon
Input
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo (aka, current account). |
collection | string (nsid) | The NSID of the record collection. |
rkey | string (record-key), at most 512 bytes, optional | The Record Key. |
validate | boolean, optional | Can be set to ‘false’ to skip Lexicon schema validation of record data, ‘true’ to require it, or leave unset to validate only for known Lexicons. |
record | unknown | The record itself. Must contain a $type field. |
swapCommit | string (cid), optional | Compare and swap with the previous commit by CID. |
Output
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | |
cid | string (cid) | |
commit | com.atproto.repo.defs#commitMeta, optional | |
validationStatus | string, valid, unknown, optional |
com.atproto.repo.deleteRecord
Section titled “com.atproto.repo.deleteRecord”Delete a repository record, or ensure it doesn’t exist. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.repo.deleteRecord - CLI
pds repo delete-record- MCP
repo_delete_record- Errors
InvalidSwap- Specified in
- The repository's records · lexicon
Input
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo (aka, current account). |
collection | string (nsid) | The NSID of the record collection. |
rkey | string (record-key) | The Record Key. |
swapRecord | string (cid), optional | Compare and swap with the previous record by CID. |
swapCommit | string (cid), optional | Compare and swap with the previous commit by CID. |
Output
| Name | Type | Description |
|---|---|---|
commit | com.atproto.repo.defs#commitMeta, optional |
com.atproto.repo.describeRepo
Section titled “com.atproto.repo.describeRepo”Get information about an account and repository, including the list of collections. Does not require auth.
- XRPC
- GET
/xrpc/com.atproto.repo.describeRepo - CLI
pds repo describe-repo- MCP
repo_describe_repo- Specified in
- The repository's records · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo. |
Output
| Name | Type | Description |
|---|---|---|
handle | string (handle) | |
did | string (did) | |
didDoc | unknown | The complete DID document for this account. |
collections | array of string (nsid) | List of all the collections (NSIDs) for which this repo contains at least one record. |
handleIsCorrect | boolean | Indicates if handle is currently valid (resolves bi-directionally) |
com.atproto.repo.getRecord
Section titled “com.atproto.repo.getRecord”Get a single record from a repository. Does not require auth.
- XRPC
- GET
/xrpc/com.atproto.repo.getRecord - CLI
pds repo get-record- MCP
repo_get_record- Errors
RecordNotFound- Specified in
- The repository's records · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo. |
collection | string (nsid) | The NSID of the record collection. |
rkey | string (record-key) | The Record Key. |
cid | string (cid), optional | The CID of the version of the record. If not specified, then return the most recent version. |
Output
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | |
cid | string (cid), optional | |
value | unknown |
com.atproto.repo.importRepo
Section titled “com.atproto.repo.importRepo”Import a repo in the form of a CAR file. Requires Content-Length HTTP header to be set.
- XRPC
- POST
/xrpc/com.atproto.repo.importRepo - CLI
pds repo import-repo- MCP
- none
- Input
application/vnd.ipld.car- Specified in
- Moving an account between servers · lexicon
com.atproto.repo.listMissingBlobs
Section titled “com.atproto.repo.listMissingBlobs”Returns a list of missing blobs for the requesting account. Intended to be used in the account migration flow.
- XRPC
- GET
/xrpc/com.atproto.repo.listMissingBlobs - CLI
pds repo list-missing-blobs- MCP
repo_list_missing_blobs- Specified in
- Moving an account between servers · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
limit | integer, 1 to 1000, default 500, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
blobs | array of recordBlob |
com.atproto.repo.listRecords
Section titled “com.atproto.repo.listRecords”List a range of records in a repository, matching a specific collection. Does not require auth.
- XRPC
- GET
/xrpc/com.atproto.repo.listRecords - CLI
pds repo list-records- MCP
repo_list_records- Specified in
- The repository's records · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo. |
collection | string (nsid) | The NSID of the record type. |
limit | integer, 1 to 100, default 50, optional | The number of records to return. |
cursor | string, optional | |
reverse | boolean, optional | Flag to reverse the order of the returned records. |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
records | array of record |
com.atproto.repo.putRecord
Section titled “com.atproto.repo.putRecord”Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.repo.putRecord - CLI
pds repo put-record- MCP
repo_put_record- Errors
InvalidSwap- Specified in
- The repository's records · lexicon
Input
| Name | Type | Description |
|---|---|---|
repo | string (at-identifier) | The handle or DID of the repo (aka, current account). |
collection | string (nsid) | The NSID of the record collection. |
rkey | string (record-key), at most 512 bytes | The Record Key. |
validate | boolean, optional | Can be set to ‘false’ to skip Lexicon schema validation of record data, ‘true’ to require it, or leave unset to validate only for known Lexicons. |
record | unknown | The record to write. |
swapRecord | string (cid), optional | Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation |
swapCommit | string (cid), optional | Compare and swap with the previous commit by CID. |
Output
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | |
cid | string (cid) | |
commit | com.atproto.repo.defs#commitMeta, optional | |
validationStatus | string, valid, unknown, optional |
com.atproto.repo.uploadBlob
Section titled “com.atproto.repo.uploadBlob”Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.repo.uploadBlob - CLI
pds repo upload-blob- MCP
- none
- Input
*/*- Specified in
- Blobs · lexicon
Output
| Name | Type | Description |
|---|---|---|
blob | blob |
com.atproto.server
Section titled “com.atproto.server”com.atproto.server.activateAccount
Section titled “com.atproto.server.activateAccount”Activates a currently deactivated account. Used to finalize account migration after the account’s repo is imported and identity is setup.
- XRPC
- POST
/xrpc/com.atproto.server.activateAccount - CLI
pds server activate-account- MCP
server_activate_account- Specified in
- Account lifecycle · lexicon
com.atproto.server.checkAccountStatus
Section titled “com.atproto.server.checkAccountStatus”Returns the status of an account, especially as pertaining to import or recovery. Can be called many times over the course of an account migration. Requires auth and can only be called pertaining to oneself.
- XRPC
- GET
/xrpc/com.atproto.server.checkAccountStatus - CLI
pds server check-account-status- MCP
server_check_account_status- Specified in
- Account lifecycle · lexicon
Output
| Name | Type | Description |
|---|---|---|
activated | boolean | |
validDid | boolean | |
repoCommit | string (cid) | |
repoRev | string | |
repoBlocks | integer | |
indexedRecords | integer | |
privateStateValues | integer | |
expectedBlobs | integer | |
importedBlobs | integer |
com.atproto.server.confirmEmail
Section titled “com.atproto.server.confirmEmail”Confirm an email using a token from com.atproto.server.requestEmailConfirmation.
- XRPC
- POST
/xrpc/com.atproto.server.confirmEmail - CLI
pds server confirm-email- MCP
server_confirm_email- Errors
AccountNotFoundExpiredTokenInvalidTokenInvalidEmail- Specified in
- Email · lexicon
Input
| Name | Type | Description |
|---|---|---|
email | string | |
token | string |
com.atproto.server.createAccount
Section titled “com.atproto.server.createAccount”Create an account. Implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.server.createAccount - CLI
pds server create-account- MCP
server_create_account- Errors
InvalidHandleInvalidPasswordInvalidInviteCodeHandleNotAvailableUnsupportedDomainUnresolvableDidIncompatibleDidDoc- Specified in
- Accounts · lexicon
Input
| Name | Type | Description |
|---|---|---|
email | string, optional | |
handle | string (handle) | Requested handle for the account. |
did | string (did), optional | Pre-existing atproto DID, being imported to a new account. |
inviteCode | string, optional | |
verificationCode | string, optional | |
verificationPhone | string, optional | |
password | string, optional | Initial account password. May need to meet instance-specific password strength requirements. |
recoveryKey | string, optional | DID PLC rotation key (aka, recovery key) to be included in PLC creation operation. |
plcOp | unknown, optional | A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented. |
Output
| Name | Type | Description |
|---|---|---|
accessJwt | string | |
refreshJwt | string | |
handle | string (handle) | |
did | string (did) | The DID of the new account. |
didDoc | unknown, optional | Complete DID document. |
com.atproto.server.createAppPassword
Section titled “com.atproto.server.createAppPassword”Create an App Password.
- XRPC
- POST
/xrpc/com.atproto.server.createAppPassword - CLI
pds server create-app-password- MCP
server_create_app_password- Output
appPassword- Errors
AccountTakedown- Specified in
- Sessions · lexicon
Input
| Name | Type | Description |
|---|---|---|
name | string | A short name for the App Password, to help distinguish them. |
privileged | boolean, optional | If an app password has ‘privileged’ access to possibly sensitive account state. Meant for use with trusted clients. |
com.atproto.server.createInviteCode
Section titled “com.atproto.server.createInviteCode”Create an invite code.
- XRPC
- POST
/xrpc/com.atproto.server.createInviteCode - CLI
pds server create-invite-code- MCP
server_create_invite_code- Specified in
- Limits · lexicon
Input
| Name | Type | Description |
|---|---|---|
useCount | integer | |
forAccount | string (did), optional |
Output
| Name | Type | Description |
|---|---|---|
code | string |
com.atproto.server.createInviteCodes
Section titled “com.atproto.server.createInviteCodes”Create invite codes.
- XRPC
- POST
/xrpc/com.atproto.server.createInviteCodes - CLI
pds server create-invite-codes- MCP
server_create_invite_codes- Specified in
- Limits · lexicon
Input
| Name | Type | Description |
|---|---|---|
codeCount | integer, default 1 | |
useCount | integer | |
forAccounts | array of string (did), optional |
Output
| Name | Type | Description |
|---|---|---|
codes | array of accountCodes |
com.atproto.server.createSession
Section titled “com.atproto.server.createSession”Create an authentication session.
- XRPC
- POST
/xrpc/com.atproto.server.createSession - CLI
pds server create-session- MCP
server_create_session- Errors
AccountTakedownAuthFactorTokenRequired- Specified in
- Accounts · lexicon
Input
| Name | Type | Description |
|---|---|---|
identifier | string | Handle or other identifier supported by the server for the authenticating user. |
password | string | |
authFactorToken | string, optional | |
allowTakendown | boolean, optional | When true, instead of throwing error for takendown accounts, a valid response with a narrow scoped token will be returned |
Output
| Name | Type | Description |
|---|---|---|
accessJwt | string | |
refreshJwt | string | |
handle | string (handle) | |
did | string (did) | |
didDoc | unknown, optional | |
email | string, optional | |
emailConfirmed | boolean, optional | |
emailAuthFactor | boolean, optional | |
active | boolean, optional | |
status | string, takendown, suspended, deactivated, optional | If active=false, this optional field indicates a possible reason for why the account is not active. If active=false and no status is supplied, then the host makes no claim for why the repository is no longer being hosted. |
com.atproto.server.deactivateAccount
Section titled “com.atproto.server.deactivateAccount”Deactivates a currently active account. Stops serving of repo, and future writes to repo until reactivated. Used to finalize account migration with the old host after the account has been activated on the new host.
- XRPC
- POST
/xrpc/com.atproto.server.deactivateAccount - CLI
pds server deactivate-account- MCP
server_deactivate_account- Specified in
- Account lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
deleteAfter | string (datetime), optional | A recommendation to server as to how long they should hold onto the deactivated account before deleting. |
com.atproto.server.deleteAccount
Section titled “com.atproto.server.deleteAccount”Delete an actor’s account with a token and password. Can only be called after requesting a deletion token. Requires auth.
- XRPC
- POST
/xrpc/com.atproto.server.deleteAccount - CLI
pds server delete-account- MCP
server_delete_account- Errors
ExpiredTokenInvalidToken- Specified in
- Account lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
did | string (did) | |
password | string | |
token | string |
com.atproto.server.deleteSession
Section titled “com.atproto.server.deleteSession”Delete the current session. Requires auth using the ‘refreshJwt’ (not the ‘accessJwt’).
- XRPC
- POST
/xrpc/com.atproto.server.deleteSession - CLI
pds server delete-session- MCP
server_delete_session- Errors
InvalidTokenExpiredToken- Specified in
- Sessions · lexicon
com.atproto.server.describeServer
Section titled “com.atproto.server.describeServer”Describes the server’s account creation requirements and capabilities. Implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.server.describeServer - CLI
pds server describe-server- MCP
server_describe_server- Specified in
- Accounts · lexicon
Output
| Name | Type | Description |
|---|---|---|
inviteCodeRequired | boolean, optional | If true, an invite code must be supplied to create an account on this instance. |
phoneVerificationRequired | boolean, optional | If true, a phone verification token must be supplied to create an account on this instance. |
blobUploadLimit | integer, optional | Maximum size of a blob that can be uploaded via com.atproto.repo.uploadBlob, in bytes. |
availableUserDomains | array of string | List of domain suffixes that can be used in account handles. |
links | links, optional | URLs of service policy documents. |
contact | contact, optional | Contact information |
did | string (did) |
com.atproto.server.getAccountInviteCodes
Section titled “com.atproto.server.getAccountInviteCodes”Get all invite codes for the current account. Requires auth.
- XRPC
- GET
/xrpc/com.atproto.server.getAccountInviteCodes - CLI
pds server get-account-invite-codes- MCP
server_get_account_invite_codes- Errors
DuplicateCreate- Specified in
- Limits · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
includeUsed | boolean, default true, optional | |
createAvailable | boolean, default true, optional | Controls whether any new ‘earned’ but not ‘created’ invites should be created. |
Output
| Name | Type | Description |
|---|---|---|
codes | array of com.atproto.server.defs#inviteCode |
com.atproto.server.getServiceAuth
Section titled “com.atproto.server.getServiceAuth”Get a signed token on behalf of the requesting DID for the requested service.
- XRPC
- GET
/xrpc/com.atproto.server.getServiceAuth - CLI
pds server get-service-auth- MCP
server_get_service_auth- Errors
BadExpiration- Specified in
- Proxying, service auth and preferences · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
aud | string, at most 2048 bytes | The DID or did#serviceId reference of the service that the token will be used to authenticate with. |
exp | integer, optional | The time in Unix Epoch seconds that the JWT expires. Defaults to 60 seconds in the future. The service may enforce certain time bounds on tokens depending on the requested scope. |
lxm | string (nsid), optional | Lexicon (XRPC) method to bind the requested token to |
Output
| Name | Type | Description |
|---|---|---|
token | string |
com.atproto.server.getSession
Section titled “com.atproto.server.getSession”Get information about the current auth session. Requires auth.
- XRPC
- GET
/xrpc/com.atproto.server.getSession - CLI
pds server get-session- MCP
server_get_session- Specified in
- Accounts · lexicon
Output
| Name | Type | Description |
|---|---|---|
handle | string (handle) | |
did | string (did) | |
didDoc | unknown, optional | |
email | string, optional | |
emailConfirmed | boolean, optional | |
emailAuthFactor | boolean, optional | |
active | boolean, optional | |
status | string, takendown, suspended, deactivated, optional | If active=false, this optional field indicates a possible reason for why the account is not active. If active=false and no status is supplied, then the host makes no claim for why the repository is no longer being hosted. |
com.atproto.server.listAppPasswords
Section titled “com.atproto.server.listAppPasswords”List all App Passwords.
- XRPC
- GET
/xrpc/com.atproto.server.listAppPasswords - CLI
pds server list-app-passwords- MCP
server_list_app_passwords- Errors
AccountTakedown- Specified in
- Sessions · lexicon
Output
| Name | Type | Description |
|---|---|---|
passwords | array of appPassword |
com.atproto.server.refreshSession
Section titled “com.atproto.server.refreshSession”Refresh an authentication session. Requires auth using the ‘refreshJwt’ (not the ‘accessJwt’).
- XRPC
- POST
/xrpc/com.atproto.server.refreshSession - CLI
pds server refresh-session- MCP
server_refresh_session- Errors
AccountTakedownInvalidTokenExpiredToken- Specified in
- Sessions · lexicon
Output
| Name | Type | Description |
|---|---|---|
accessJwt | string | |
refreshJwt | string | |
handle | string (handle) | |
did | string (did) | |
didDoc | unknown, optional | |
email | string, optional | |
emailConfirmed | boolean, optional | |
emailAuthFactor | boolean, optional | |
active | boolean, optional | |
status | string, takendown, suspended, deactivated, optional | Hosting status of the account. If not specified, then assume ‘active’. |
com.atproto.server.requestAccountDelete
Section titled “com.atproto.server.requestAccountDelete”Initiate a user account deletion via email.
- XRPC
- POST
/xrpc/com.atproto.server.requestAccountDelete - CLI
pds server request-account-delete- MCP
server_request_account_delete- Specified in
- Account lifecycle · lexicon
com.atproto.server.requestEmailConfirmation
Section titled “com.atproto.server.requestEmailConfirmation”Request an email with a code to confirm ownership of email.
- XRPC
- POST
/xrpc/com.atproto.server.requestEmailConfirmation - CLI
pds server request-email-confirmation- MCP
server_request_email_confirmation- Specified in
- Email · lexicon
com.atproto.server.requestEmailUpdate
Section titled “com.atproto.server.requestEmailUpdate”Request a token in order to update email.
- XRPC
- POST
/xrpc/com.atproto.server.requestEmailUpdate - CLI
pds server request-email-update- MCP
server_request_email_update- Specified in
- Email · lexicon
Output
| Name | Type | Description |
|---|---|---|
tokenRequired | boolean |
com.atproto.server.requestPasswordReset
Section titled “com.atproto.server.requestPasswordReset”Initiate a user account password reset via email.
- XRPC
- POST
/xrpc/com.atproto.server.requestPasswordReset - CLI
pds server request-password-reset- MCP
server_request_password_reset- Specified in
- Email · lexicon
Input
| Name | Type | Description |
|---|---|---|
email | string |
com.atproto.server.resetPassword
Section titled “com.atproto.server.resetPassword”Reset a user account password using a token.
- XRPC
- POST
/xrpc/com.atproto.server.resetPassword - CLI
pds server reset-password- MCP
server_reset_password- Errors
ExpiredTokenInvalidToken- Specified in
- Email · lexicon
Input
| Name | Type | Description |
|---|---|---|
token | string | |
password | string |
com.atproto.server.revokeAppPassword
Section titled “com.atproto.server.revokeAppPassword”Revoke an App Password by name.
- XRPC
- POST
/xrpc/com.atproto.server.revokeAppPassword - CLI
pds server revoke-app-password- MCP
server_revoke_app_password- Specified in
- Sessions · lexicon
Input
| Name | Type | Description |
|---|---|---|
name | string |
com.atproto.server.updateEmail
Section titled “com.atproto.server.updateEmail”Update an account’s email.
- XRPC
- POST
/xrpc/com.atproto.server.updateEmail - CLI
pds server update-email- MCP
server_update_email- Errors
ExpiredTokenInvalidTokenTokenRequired- Specified in
- Email · lexicon
Input
| Name | Type | Description |
|---|---|---|
email | string | |
emailAuthFactor | boolean, optional | |
token | string, optional | Requires a token from com.atproto.sever.requestEmailUpdate if the account’s email has been confirmed. |
com.atproto.space
Section titled “com.atproto.space”com.atproto.space.applyWrites
Section titled “com.atproto.space.applyWrites”Apply a batch transaction of creates, updates, and deletes to a space repo. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.applyWrites - CLI
pds space apply-writes- MCP
space_apply_writes- Errors
SpaceNotFoundRecordNotFoundRecordAlreadyExists- Specified in
- The space repo · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
validate | boolean, optional | Can be set to ‘false’ to skip Lexicon schema validation of record data across all operations, ‘true’ to require it, or leave unset to validate only for known Lexicons. |
writes | array of one of create, update, delete |
Output
| Name | Type | Description |
|---|---|---|
results | array of one of createResult, updateResult, deleteResult, optional |
com.atproto.space.authorizeSpaceSync
Section titled “com.atproto.space.authorizeSpaceSync”Authorize syncing a space, returning a new credential for reading data across it and the space’s current revision, and optionally registering for notifications of updates to it. Depending on the space’s policy, a delegation token and/or client attestation may be required. Implemented by the space host.
- XRPC
- POST
/xrpc/com.atproto.space.authorizeSpaceSync - CLI
pds space authorize-space-sync- MCP
space_authorize_space_sync- Errors
SpaceNotFoundSpaceDeletedAccountNotAuthorizedAppNotAuthorizedNotAuthorizedInvalidDelegationTokenInvalidClientAttestationRegistrationNotConfirmedRepoTakendownRepoDeactivated- Specified in
- Spaces: credentials · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
credentialKey | string | P-256 did:key that the credential is bound to. |
delegationToken | string, optional | Obtained from getDelegationToken. |
clientAttestation | string, optional | |
notify | notify, optional | Register an endpoint to be notified of updates to the space via notifySpaceUpdate. The registration stays active while this credential is valid. After it expires, the endpoint receives only a prompt to reauthorize, or notice of the space’s deletion. |
Output
| Name | Type | Description |
|---|---|---|
credential | string | |
spaceRev | string (tid), optional | The space’s current revision. Omitted before the space’s first update. |
com.atproto.space.clearRecords
Section titled “com.atproto.space.clearRecords”Delete all records in the authenticated account’s space repo. In the space authority’s repo, records published from the space’s configuration (such as its policy) are kept. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.clearRecords - CLI
pds space clear-records- MCP
space_clear_records- Specified in
- The space repo · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) |
com.atproto.space.createRecord
Section titled “com.atproto.space.createRecord”Create a single new record in a space repo. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.createRecord - CLI
pds space create-record- MCP
space_create_record- Errors
SpaceNotFoundRecordAlreadyExists- Specified in
- The space repo · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
collection | string (nsid) | |
rkey | string (record-key), optional | |
validate | boolean, optional | Can be set to ‘false’ to skip Lexicon schema validation of record data, ‘true’ to require it, or leave unset to validate only for known Lexicons. |
record | unknown | The record itself. Must contain a $type field. |
Output
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | |
cid | string (cid) | |
validationStatus | string, valid, unknown, optional |
com.atproto.space.createSpace
Section titled “com.atproto.space.createSpace”Create a new space, with the authenticated account as its authority. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.createSpace - CLI
pds space create-space- MCP
space_create_space- Errors
SpaceAlreadyExistsUnsupportedPolicy- Specified in
- Spaces: policies and the space lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
spaceType | string (nsid) | |
skey | string (record-key), optional | Space key. Generated as a TID if not provided. |
policy | one of com.atproto.personalspace.policy, com.atproto.memberspace.policy, com.atproto.managedspace.policy | PDSes must support all of the listed policies. Other space hosts may support only some of them, and any host may support policies beyond those listed. |
Output
| Name | Type | Description |
|---|---|---|
space | string (space-ref) |
com.atproto.space.deleteRecord
Section titled “com.atproto.space.deleteRecord”Delete a record from a space repo, or ensure it doesn’t exist. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.deleteRecord - CLI
pds space delete-record- MCP
space_delete_record- Errors
SpaceNotFound- Specified in
- The space repo · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
collection | string (nsid) | |
rkey | string (record-key) |
com.atproto.space.deleteSpace
Section titled “com.atproto.space.deleteSpace”Delete a space, along with the authority’s space repo. Requires auth as the space authority, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.deleteSpace - CLI
pds space delete-space- MCP
space_delete_space- Errors
SpaceNotFoundNotAuthorized- Specified in
- Spaces: policies and the space lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) |
com.atproto.space.exportSpaceMeta
Section titled “com.atproto.space.exportSpaceMeta”Export a space’s state, such as its policy and member list, as a STAR file for account migration. Requires auth as the space authority, implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.exportSpaceMeta - CLI
pds space export-space-meta- MCP
- none
- Output
application/vnd.dasl.star- Errors
SpaceNotFoundNotAuthorized- Specified in
- Spaces: policies and the space lifecycle · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) |
com.atproto.space.getBlob
Section titled “com.atproto.space.getBlob”Get a blob referenced by a record in a space repo. Returns the full blob as originally uploaded. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.getBlob - CLI
pds space get-blob- MCP
- none
- Output
*/*- Errors
BlobNotFoundSpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Spaces: a repo whole, its blobs, and migration · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
cid | string (cid) |
com.atproto.space.getDelegationToken
Section titled “com.atproto.space.getDelegationToken”Get a delegation token for a space, to exchange with the space host for a space credential. Requires auth, implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.getDelegationToken - CLI
pds space get-delegation-token- MCP
space_get_delegation_token- Specified in
- Spaces: credentials · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) |
Output
| Name | Type | Description |
|---|---|---|
token | string |
com.atproto.space.getLatestCommit
Section titled “com.atproto.space.getLatestCommit”Get the current commit of a space repo. Responses are authenticated with a MAC. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.getLatestCommit - CLI
pds space get-latest-commit- MCP
space_get_latest_commit- Errors
InvalidSpaceMacSpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- The space repo · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) |
Output
| Name | Type | Description |
|---|---|---|
commit | com.atproto.space.defs#commit |
com.atproto.space.getRecord
Section titled “com.atproto.space.getRecord”Get a single record from a space repo. Responses are authenticated with a MAC. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.getRecord - CLI
pds space get-record- MCP
space_get_record- Errors
InvalidSpaceMacRecordNotFoundSpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- The space repo · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
collection | string (nsid) | |
rkey | string (record-key) |
Output
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | |
cid | string (cid) | |
value | unknown |
com.atproto.space.getRepo
Section titled “com.atproto.space.getRepo”Download a space repo as a STAR file. Responses are authenticated with a MAC. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.getRepo - CLI
pds space get-repo- MCP
- none
- Output
application/vnd.dasl.star- Errors
InvalidSpaceMacSpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Spaces: a repo whole, its blobs, and migration · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) |
com.atproto.space.getSpace
Section titled “com.atproto.space.getSpace”Get a space and its policy. Requires auth as the space authority, implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.getSpace - CLI
pds space get-space- MCP
space_get_space- Errors
SpaceNotFoundNotAuthorized- Specified in
- Spaces: policies and the space lifecycle · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) |
Output
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
policy | one of com.atproto.personalspace.policy, com.atproto.memberspace.policy, com.atproto.managedspace.policy | PDSes must support all of the listed policies. Other space hosts may support only some of them, and any host may support policies beyond those listed. |
com.atproto.space.importRepo
Section titled “com.atproto.space.importRepo”Import the authenticated account’s space repo from a STAR file, for account migration. If the account is the space’s authority, the space must first be imported with importSpaceMeta. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.importRepo - CLI
pds space import-repo- MCP
- none
- Input
application/vnd.dasl.star- Errors
SpaceNotFoundInvalidRepoFileRepoMismatch- Specified in
- Spaces: a repo whole, its blobs, and migration · lexicon
com.atproto.space.importSpaceMeta
Section titled “com.atproto.space.importSpaceMeta”Import a space’s state from an archive produced by exportSpaceMeta, for account migration. Must be called before importing the authority’s space repo with importRepo. Requires auth as the space authority, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.importSpaceMeta - CLI
pds space import-space-meta- MCP
- none
- Input
application/vnd.dasl.star- Errors
NotAuthorizedUnsupportedPolicyInvalidSpaceMeta- Specified in
- Spaces: policies and the space lifecycle · lexicon
com.atproto.space.listBlobs
Section titled “com.atproto.space.listBlobs”List blob CIDs referenced by records in a space repo. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.listBlobs - CLI
pds space list-blobs- MCP
space_list_blobs- Errors
SpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Spaces: a repo whole, its blobs, and migration · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
limit | integer, 1 to 1000, default 500, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
cids | array of string (cid) |
com.atproto.space.listRecords
Section titled “com.atproto.space.listRecords”List records in a space repo, optionally filtered by collection. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.listRecords - CLI
pds space list-records- MCP
space_list_records- Errors
SpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivatedInvalidCursor- Specified in
- The space repo · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
collection | string (nsid), optional | If omitted, lists records across all collections. |
limit | integer, 1 to 1000, default 50, optional | |
cursor | string, optional | |
excludeValues | boolean, default false, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
records | array of record |
com.atproto.space.listRepoOps
Section titled “com.atproto.space.listRepoOps”List operations on a space repo after a given revision. Used for incremental sync. Hosts may truncate the log, so use getRepo for a full sync. Responses are authenticated with a MAC. Requires auth as the repo’s account or with a space credential; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.listRepoOps - CLI
pds space list-repo-ops- MCP
space_list_repo_ops- Errors
InvalidSpaceMacSpaceNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivatedInvalidCursor- Specified in
- The space repo · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
since | string (tid), optional | |
limit | integer, 1 to 1000, default 100, optional | |
cursor | string, optional | |
excludeValues | boolean, default false, optional |
Output
| Name | Type | Description |
|---|---|---|
ops | array of opEntry | |
commit | com.atproto.space.defs#commit | The repo’s current commit. A syncer compares it against its own set hash once it has applied the last page, which has no cursor. |
cursor | string, optional |
com.atproto.space.listSpaces
Section titled “com.atproto.space.listSpaces”List spaces that the authenticated account has written to or is the authority for. Requires auth, implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.space.listSpaces - CLI
pds space list-spaces- MCP
space_list_spaces- Errors
InvalidCursor- Specified in
- The space repo · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
spaceDid | string (did), optional | Filter to spaces with this DID as their authority. |
spaceType | string (nsid), optional | |
limit | integer, 1 to 100, default 50, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
spaces | array of spaceView |
com.atproto.space.listWriters
Section titled “com.atproto.space.listWriters”List the repos in a space’s writer set, with the latest known state of each: its current revision, or its removal from the writer set. Requires a space credential, implemented by the space host.
- XRPC
- GET
/xrpc/com.atproto.space.listWriters - CLI
pds space list-writers- MCP
space_list_writers- Errors
SpaceNotFoundRepoTakendownRepoDeactivated- Specified in
- Spaces: write notifications, the writer set and syncers · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
limit | integer, 1 to 1000, default 100, optional | |
cursor | string, optional | Return repos updated after this space revision. Removed repos may be garbage collected after 72 hrs, so a syncer whose last seen space revision is older should list the whole writer set instead. |
Output
| Name | Type | Description |
|---|---|---|
repos | array of one of com.atproto.space.defs#repoWrite, com.atproto.space.defs#repoRemoved | The latest update to each repo, ordered by spaceRev, ascending. prevSpaceRev is not set. |
cursor | string, optional |
com.atproto.space.notifyCredentialsRevoked
Section titled “com.atproto.space.notifyCredentialsRevoked”Notify a repo host that space credentials have been revoked. Sent by the space host. Requires service auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.notifyCredentialsRevoked - CLI
pds space notify-credentials-revoked- MCP
space_notify_credentials_revoked- Specified in
- Spaces: credentials · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
credentials | array of string, at most 100 | The IDs (jti) of the revoked credentials. |
com.atproto.space.notifyRepoUpdate
Section titled “com.atproto.space.notifyRepoUpdate”Notify the space host that a space repo has been updated. Sent by repo hosts, with service auth.
- XRPC
- POST
/xrpc/com.atproto.space.notifyRepoUpdate - CLI
pds space notify-repo-update- MCP
space_notify_repo_update- Errors
SpaceNotFoundFutureRev- Specified in
- Spaces: write notifications, the writer set and syncers · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
repoRev | string (tid) | |
data | bytes |
com.atproto.space.putRecord
Section titled “com.atproto.space.putRecord”Write a record in a space repo, creating or updating it as needed. Requires auth, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.putRecord - CLI
pds space put-record- MCP
space_put_record- Errors
SpaceNotFound- Specified in
- The space repo · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) | |
collection | string (nsid) | |
rkey | string (record-key) | |
validate | boolean, optional | Can be set to ‘false’ to skip Lexicon schema validation of record data, ‘true’ to require it, or leave unset to validate only for known Lexicons. |
record | unknown |
Output
| Name | Type | Description |
|---|---|---|
uri | string (at-uri) | |
cid | string (cid) | |
validationStatus | string, valid, unknown, optional |
com.atproto.space.removeWriter
Section titled “com.atproto.space.removeWriter”Remove an account from a space’s writer set, as returned by listWriters. The removal is sent to registered syncers. The account is added back if it makes another authorized write to the space. Does nothing if the account is not in the writer set. Requires auth as the space authority, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.removeWriter - CLI
pds space remove-writer- MCP
space_remove_writer- Errors
SpaceNotFoundNotAuthorized- Specified in
- Spaces: policies and the space lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
repo | string (did) |
com.atproto.space.updateSpace
Section titled “com.atproto.space.updateSpace”Replace the policy of a space. Changing to a different policy type discards state held by the previous policy, such as a member list. Requires auth as the space authority, implemented by PDS.
- XRPC
- POST
/xrpc/com.atproto.space.updateSpace - CLI
pds space update-space- MCP
space_update_space- Errors
SpaceNotFoundNotAuthorizedUnsupportedPolicy- Specified in
- Spaces: policies and the space lifecycle · lexicon
Input
| Name | Type | Description |
|---|---|---|
space | string (space-ref) | |
policy | one of com.atproto.personalspace.policy, com.atproto.memberspace.policy, com.atproto.managedspace.policy | PDSes must support all of the listed policies. Other space hosts may support only some of them, and any host may support policies beyond those listed. |
com.atproto.sync
Section titled “com.atproto.sync”com.atproto.sync.getBlob
Section titled “com.atproto.sync.getBlob”Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.sync.getBlob - CLI
pds sync get-blob- MCP
- none
- Output
*/*- Errors
BlobNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Blobs · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the account. |
cid | string (cid) | The CID of the blob to fetch |
com.atproto.sync.getBlocks
Section titled “com.atproto.sync.getBlocks”Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.sync.getBlocks - CLI
pds sync get-blocks- MCP
- none
- Output
application/vnd.ipld.car- Errors
BlockNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Federation: what a relay reads · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the repo. |
cids | array of string (cid) |
com.atproto.sync.getLatestCommit
Section titled “com.atproto.sync.getLatestCommit”Get the current commit CID & revision of the specified repo. Does not require auth.
- XRPC
- GET
/xrpc/com.atproto.sync.getLatestCommit - CLI
pds sync get-latest-commit- MCP
sync_get_latest_commit- Errors
RepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Sync and the firehose · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the repo. |
Output
| Name | Type | Description |
|---|---|---|
cid | string (cid) | |
rev | string (tid) |
com.atproto.sync.getRecord
Section titled “com.atproto.sync.getRecord”Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.
- XRPC
- GET
/xrpc/com.atproto.sync.getRecord - CLI
pds sync get-record- MCP
- none
- Output
application/vnd.ipld.car- Errors
RecordNotFoundRepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Federation: what a relay reads · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the repo. |
collection | string (nsid) | |
rkey | string (record-key) | Record Key |
com.atproto.sync.getRepo
Section titled “com.atproto.sync.getRepo”Download a repository export as CAR file. Optionally only a ‘diff’ since a previous revision. Does not require auth; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.sync.getRepo - CLI
pds sync get-repo- MCP
- none
- Output
application/vnd.ipld.car- Errors
RepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Sync and the firehose · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the repo. |
since | string (tid), optional | The revision (‘rev’) of the repo to create a diff from. |
com.atproto.sync.getRepoStatus
Section titled “com.atproto.sync.getRepoStatus”Get the hosting status for a repository, on this server. Expected to be implemented by PDS and Relay.
- XRPC
- GET
/xrpc/com.atproto.sync.getRepoStatus - CLI
pds sync get-repo-status- MCP
sync_get_repo_status- Errors
RepoNotFound- Specified in
- Federation: what a relay reads · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the repo. |
Output
| Name | Type | Description |
|---|---|---|
did | string (did) | |
active | boolean | |
status | string, takendown, suspended, deleted, deactivated, desynchronized, throttled, optional | If active=false, this optional field indicates a possible reason for why the account is not active. If active=false and no status is supplied, then the host makes no claim for why the repository is no longer being hosted. |
rev | string (tid), optional | Optional field, the current rev of the repo, if active=true |
com.atproto.sync.listBlobs
Section titled “com.atproto.sync.listBlobs”List blob CIDs for an account, since some repo revision. Does not require auth; implemented by PDS.
- XRPC
- GET
/xrpc/com.atproto.sync.listBlobs - CLI
pds sync list-blobs- MCP
sync_list_blobs- Errors
RepoNotFoundRepoTakendownRepoSuspendedRepoDeactivated- Specified in
- Blobs · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
did | string (did) | The DID of the repo. |
since | string (tid), optional | Optional revision of the repo to list blobs since. |
limit | integer, 1 to 1000, default 500, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
cids | array of string (cid) |
com.atproto.sync.listRepos
Section titled “com.atproto.sync.listRepos”Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.
- XRPC
- GET
/xrpc/com.atproto.sync.listRepos - CLI
pds sync list-repos- MCP
sync_list_repos- Specified in
- Federation: what a relay reads · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
limit | integer, 1 to 1000, default 500, optional | |
cursor | string, optional |
Output
| Name | Type | Description |
|---|---|---|
cursor | string, optional | |
repos | array of repo |
com.atproto.sync.subscribeRepos
Section titled “com.atproto.sync.subscribeRepos”Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.
- XRPC
- WS
/xrpc/com.atproto.sync.subscribeRepos - CLI
- none
- MCP
- none
- Errors
FutureCursorConsumerTooSlow- Specified in
- Sync and the firehose · lexicon
Parameters
| Name | Type | Description |
|---|---|---|
cursor | integer, optional | The last known event seq number to backfill from. |