The core AT Protocol XRPC API covering server identity, repository management, account administration, moderation/labeling, and data synchronization. Endpoints are accessed via HTTP GET (queries) and POST (procedures) at /xrpc/{NSID} on any PDS host or the Bluesky-hosted services at bsky.social and bsky.network.
openapi: 3.0.3
info:
title: AT Protocol Core API (com.atproto)
description: >-
The core AT Protocol XRPC API covering server identity, repository
management, account administration, moderation/labeling, and data
synchronization. Endpoints are accessed via HTTP GET (queries) and POST
(procedures) at /xrpc/{NSID} on any PDS host or the Bluesky-hosted
services at bsky.social and bsky.network. Schemas are defined using
Lexicon, AT Protocol's schema definition language.
version: '1.0.0'
contact:
name: AT Protocol
url: https://atproto.com/
license:
name: MIT / Apache-2.0
url: https://github.com/bluesky-social/atproto/blob/main/LICENSE.txt
externalDocs:
description: AT Protocol XRPC Specification
url: https://atproto.com/specs/xrpc
servers:
- url: https://bsky.social/xrpc
description: Bluesky PDS (Personal Data Server)
- url: https://bsky.network/xrpc
description: Bluesky Relay / BGS
- url: https://{pds_host}/xrpc
description: Self-hosted PDS
variables:
pds_host:
default: bsky.social
description: Hostname of the Personal Data Server
security:
- bearerAuth: []
- {}
tags:
- name: server
description: Server management, session creation, account administration
- name: identity
description: DID and handle resolution, identity management
- name: repo
description: Repository management, record CRUD operations
- name: sync
description: Data synchronization, firehose, blob access
- name: moderation
description: Moderation reports and actions
- name: label
description: Content labeling
paths:
/com.atproto.server.describeServer:
get:
operationId: com_atproto_server_describeServer
summary: Describe Server
description: >-
Describes the server's account creation requirements and capabilities.
Implemented by PDS. No authentication required.
tags:
- server
security:
- {}
responses:
'200':
description: Server description
content:
application/json:
schema:
$ref: '#/components/schemas/ServerDescription'
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.server.createSession:
post:
operationId: com_atproto_server_createSession
summary: Create Session
description: Create an authentication session (login).
tags:
- server
security:
- {}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionInput'
responses:
'200':
description: Session created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.server.deleteSession:
post:
operationId: com_atproto_server_deleteSession
summary: Delete Session
description: Delete the current session (logout).
tags:
- server
responses:
'200':
description: Session deleted
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.server.getSession:
get:
operationId: com_atproto_server_getSession
summary: Get Session
description: Get information about the current auth session.
tags:
- server
responses:
'200':
description: Current session info
content:
application/json:
schema:
$ref: '#/components/schemas/SessionInfo'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.server.refreshSession:
post:
operationId: com_atproto_server_refreshSession
summary: Refresh Session
description: Refresh an authentication session using a refresh JWT.
tags:
- server
security:
- refreshAuth: []
responses:
'200':
description: Session refreshed
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.server.createAccount:
post:
operationId: com_atproto_server_createAccount
summary: Create Account
description: Create an account. Implemented by PDS.
tags:
- server
security:
- {}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccountInput'
responses:
'200':
description: Account created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccountOutput'
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.server.deleteAccount:
post:
operationId: com_atproto_server_deleteAccount
summary: Delete Account
description: Delete an actor's account with a token and password.
tags:
- server
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- did
- password
- token
properties:
did:
type: string
description: DID of account to delete
password:
type: string
token:
type: string
description: Confirmation token received via email
responses:
'200':
description: Account deleted
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.server.checkAccountStatus:
get:
operationId: com_atproto_server_checkAccountStatus
summary: Check Account Status
description: Returns the status of an account, especially as pertaining to import or recovery.
tags:
- server
responses:
'200':
description: Account status
content:
application/json:
schema:
$ref: '#/components/schemas/AccountStatus'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.identity.resolveHandle:
get:
operationId: com_atproto_identity_resolveHandle
summary: Resolve Handle
description: Resolves a handle (eg, username) to a DID.
tags:
- identity
security:
- {}
parameters:
- name: handle
in: query
required: true
description: The handle to resolve. If not supplied, will resolve the host's own handle.
schema:
type: string
responses:
'200':
description: Resolved DID
content:
application/json:
schema:
type: object
required:
- did
properties:
did:
type: string
description: The DID of the resolved handle
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.identity.updateHandle:
post:
operationId: com_atproto_identity_updateHandle
summary: Update Handle
description: Updates the current account's handle.
tags:
- identity
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- handle
properties:
handle:
type: string
description: The new handle.
responses:
'200':
description: Handle updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.identity.resolveDid:
get:
operationId: com_atproto_identity_resolveDid
summary: Resolve DID
description: Resolves a DID to a DID document.
tags:
- identity
security:
- {}
parameters:
- name: did
in: query
required: true
description: The DID to resolve.
schema:
type: string
responses:
'200':
description: DID document
content:
application/json:
schema:
type: object
description: DID document (W3C DID Core format)
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.repo.getRecord:
get:
operationId: com_atproto_repo_getRecord
summary: Get Record
description: Get a single record from a repository. Does not require auth.
tags:
- repo
security:
- {}
parameters:
- name: repo
in: query
required: true
description: The handle or DID of the repo.
schema:
type: string
- name: collection
in: query
required: true
description: The NSID of the record collection.
schema:
type: string
- name: rkey
in: query
required: true
description: The Record Key.
schema:
type: string
- name: cid
in: query
required: false
description: The CID of the version of the record. If not specified, returns the most recent version.
schema:
type: string
responses:
'200':
description: Record data
content:
application/json:
schema:
$ref: '#/components/schemas/RepoRecord'
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.repo.createRecord:
post:
operationId: com_atproto_repo_createRecord
summary: Create Record
description: Create a single new repository record. Requires auth, implemented by PDS.
tags:
- repo
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRecordInput'
responses:
'200':
description: Record created
content:
application/json:
schema:
$ref: '#/components/schemas/RecordRef'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.repo.putRecord:
post:
operationId: com_atproto_repo_putRecord
summary: Put Record
description: >-
Write a repository record, creating or updating it as needed. Requires
auth, implemented by PDS.
tags:
- repo
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PutRecordInput'
responses:
'200':
description: Record written
content:
application/json:
schema:
$ref: '#/components/schemas/RecordRef'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.repo.deleteRecord:
post:
operationId: com_atproto_repo_deleteRecord
summary: Delete Record
description: Delete a repository record, or ensure it doesn't exist. Implemented by PDS.
tags:
- repo
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- repo
- collection
- rkey
properties:
repo:
type: string
description: The handle or DID of the repo (aka, current account).
collection:
type: string
description: The NSID of the record collection.
rkey:
type: string
description: The Record Key.
swapRecord:
type: string
description: Compare and swap with the previous record by CID.
swapCommit:
type: string
description: Compare and swap with the previous commit by CID.
responses:
'200':
description: Record deleted
content:
application/json:
schema:
type: object
properties:
commit:
$ref: '#/components/schemas/CommitMeta'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.repo.listRecords:
get:
operationId: com_atproto_repo_listRecords
summary: List Records
description: List a range of records in a repository, matching a specific collection.
tags:
- repo
security:
- {}
parameters:
- name: repo
in: query
required: true
description: The handle or DID of the repo.
schema:
type: string
- name: collection
in: query
required: true
description: The NSID of the record type.
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: cursor
in: query
required: false
schema:
type: string
- name: reverse
in: query
required: false
description: Flag to reverse the order of the returned records.
schema:
type: boolean
responses:
'200':
description: List of records
content:
application/json:
schema:
type: object
required:
- records
properties:
cursor:
type: string
records:
type: array
items:
$ref: '#/components/schemas/RepoRecord'
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.repo.uploadBlob:
post:
operationId: com_atproto_repo_uploadBlob
summary: Upload Blob
description: >-
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) are enforced when the
reference is created. Requires auth, implemented by PDS.
tags:
- repo
requestBody:
required: true
content:
'*/*':
schema:
type: string
format: binary
responses:
'200':
description: Blob uploaded
content:
application/json:
schema:
type: object
required:
- blob
properties:
blob:
$ref: '#/components/schemas/BlobRef'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/com.atproto.repo.describeRepo:
get:
operationId: com_atproto_repo_describeRepo
summary: Describe Repo
description: Get information about an account and repository, including the list of collections. Does not require auth.
tags:
- repo
security:
- {}
parameters:
- name: repo
in: query
required: true
description: The handle or DID of the repo.
schema:
type: string
responses:
'200':
description: Repository description
content:
application/json:
schema:
$ref: '#/components/schemas/RepoDescription'
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.sync.getRepo:
get:
operationId: com_atproto_sync_getRepo
summary: Get Repo
description: >-
Download a repository export as CAR file. Optionally only a subset of
commits. Does not require auth; implemented by PDS.
tags:
- sync
security:
- {}
parameters:
- name: did
in: query
required: true
description: The DID of the repo.
schema:
type: string
- name: since
in: query
required: false
description: The revision (''rev'') of the repo to create a diff from.
schema:
type: string
responses:
'200':
description: CAR file binary
content:
application/vnd.ipld.car:
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.sync.getBlob:
get:
operationId: com_atproto_sync_getBlob
summary: Get Blob
description: Get a blob associated with a given account. Does not require auth.
tags:
- sync
security:
- {}
parameters:
- name: did
in: query
required: true
description: The DID of the account.
schema:
type: string
- name: cid
in: query
required: true
description: The CID of the blob to fetch.
schema:
type: string
responses:
'200':
description: Blob data
content:
'*/*':
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
/com.atproto.sync.listRepos:
get:
operationId: com_atproto_sync_listRepos
summary: List Repos
description: Enumerates all the DID, rev, and CID triples for all repos hosted by this service.
tags:
- sync
security:
- {}
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 500
- name: cursor
in: query
required: false
schema:
type: string
responses:
'200':
description: List of repos
content:
application/json:
schema:
type: object
required:
- repos
properties:
cursor:
type: string
repos:
type: array
items:
$ref: '#/components/schemas/RepoRef'
'400':
$ref: '#/components/responses/BadRequest'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Access JWT obtained from createSession or refreshSession
refreshAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Refresh JWT obtained from createSession
responses:
BadRequest:
description: Bad request or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error name/code
message:
type: string
description: Human-readable error message
Session:
type: object
required:
- accessJwt
- refreshJwt
- handle
- did
properties:
accessJwt:
type: string
description: Short-lived access token
refreshJwt:
type: string
description: Long-lived refresh token
handle:
type: string
description: The user's handle
did:
type: string
description: The user's DID (Decentralized Identifier)
didDoc:
type: object
description: Full DID document
additionalProperties: true
email:
type: string
description: Email address (if available)
emailConfirmed:
type: boolean
emailAuthFactor:
type: boolean
active:
type: boolean
status:
type: string
description: Account status if not active
enum:
- takendown
- suspended
- deactivated
SessionInfo:
type: object
required:
- handle
- did
properties:
handle:
type: string
did:
type: string
didDoc:
type: object
additionalProperties: true
email:
type: string
emailConfirmed:
type: boolean
emailAuthFactor:
type: boolean
active:
type: boolean
status:
type: string
CreateSessionInput:
type: object
required:
- identifier
- password
properties:
identifier:
type: string
description: Handle or other identifier supported by the server
password:
type: string
authFactorToken:
type: string
description: Two-factor authentication token
allowTakendown:
type: boolean
description: When true, return a narrow-scoped token for takendown accounts
CreateAccountInput:
type: object
required:
- handle
properties:
email:
type: string
handle:
type: string
description: Requested handle for the account
did:
type: string
description: Pre-existing atproto DID, being imported to a new account
inviteCode:
type: string
verificationCode:
type: string
verificationPhone:
type: string
password:
type: string
description: Initial account password
recoveryKey:
type: string
description: DID PLC rotation key (recovery key)
CreateAccountOutput:
type: object
required:
- accessJwt
- refreshJwt
- handle
- did
properties:
accessJwt:
type: string
refreshJwt:
type: string
handle:
type: string
did:
type: string
didDoc:
type: object
additionalProperties: true
AccountStatus:
type: object
required:
- activated
- validDid
- repoCommit
- repoRev
- repoBlocks
- indexedRecords
- privateStateValues
- expectedBlobs
- importedBlobs
properties:
activated:
type: boolean
validDid:
type: boolean
repoCommit:
type: string
repoRev:
type: string
repoBlocks:
type: integer
indexedRecords:
type: integer
privateStateValues:
type: integer
expectedBlobs:
type: integer
importedBlobs:
type: integer
ServerDescription:
type: object
required:
- did
- availableUserDomains
properties:
inviteCodeRequired:
type: boolean
description: If true, an invite code must be supplied to create an account
phoneVerificationRequired:
type: boolean
description: If true, a phone verification token must be supplied
availableUserDomains:
type: array
description: List of domain suffixes that can be used in account handles
items:
type: string
links:
type: object
properties:
privacyPolicy:
type: string
format: uri
termsOfService:
type: string
format: uri
contact:
type: object
properties:
email:
type: string
did:
type: string
description: DID of the server
RepoRecord:
type: object
required:
- uri
- value
properties:
uri:
type: string
description: AT URI of the record
cid:
type: string
description: Content identifier (CID)
value:
type: object
description: The record data
additionalProperties: true
RecordRef:
type: object
required:
- uri
- cid
properties:
uri:
type: string
description: AT URI of the record
cid:
type: string
description: Content identifier
commit:
$ref: '#/components/schemas/CommitMeta'
validationStatus:
type: string
enum:
- valid
- unknown
CommitMeta:
type: object
required:
- cid
- rev
properties:
cid:
type: string
rev:
type: string
CreateRecordInput:
type: object
required:
- repo
- collection
- record
properties:
repo:
type: string
description: The handle or DID of the repo (aka, current account).
collection:
type: string
description: The NSID of the record collection.
rkey:
type: string
description: The Record Key.
validate:
type: boolean
description: Can be set to 'false' to skip Lexicon schema validation of record data.
record:
type: object
description: The record itself. Must contain a $type field.
additionalProperties: true
swapCommit:
type: string
description: Compare and swap with the previous commit by CID.
PutRecordInput:
type: object
required:
- repo
- collection
- rkey
- record
properties:
repo:
type: string
collection:
type: string
rkey:
type: string
validate:
type: boolean
record:
type: object
additionalProperties: true
swapRecord:
type: string
swapCommit:
type: string
RepoDescription:
type: object
required:
- handle
- did
- didDoc
- collections
- handleIsCorrect
properties:
handle:
type: string
did:
type: string
didDoc:
type: object
additionalProperties: true
collections:
type: array
description: List of all the collections (NSIDs) an account has at least one record in.
items:
type: string
handleIsCorrect:
type: boolean
description: Indicates if handle is currently valid (resolves correctly)
BlobRef:
type: object
required:
- '$type'
- ref
- mimeType
- size
properties:
'$type':
type: string
example: blob
ref:
type: object
properties:
'$link':
type: string
mimeType:
type: string
size:
type: integer
RepoRef:
type: object
required:
- did
- head
- rev
properties:
did:
type: string
head:
type: string
rev:
type: string
active:
type: boolean
status:
type: string