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