Bluesky Server API

openapi: 3.1.0
info:
  title: Bluesky Social Actor Profiles Server API
  description: "The Bluesky Social API provides programmatic access to the Bluesky social network built on the AT Protocol. \n\nThis API enables developers to:\n- Manage user profiles and preferences\n- Create, read, and interact with posts and feeds\n- Handle social graph operations (follows, blocks, mutes)\n- Process notifications and conversations\n- Moderate content and manage labels\n- Synchronize repository data\n\nAuthentication is handled via Bearer tokens. Public endpoints can be accessed directly at https://public.api.bsky.app, while authenticated requests should be made to the user's Personal Data Server (PDS).\n\nFor more information, visit the [Bluesky API Documentation](https://docs.bsky.app)."
  version: 1.0.0
  contact:
    name: Bluesky Support
    url: https://bsky.app
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://bsky.social/xrpc
  description: Bluesky Social PDS
- url: https://public.api.bsky.app/xrpc
  description: Public Bluesky AppView API (unauthenticated endpoints)
tags:
- name: Server
  description: Operations for server management and authentication.
paths:
  /xrpc/com.atproto.server.activateAccount:
    post:
      operationId: serverActivateAccount
      summary: Bluesky Activates a currently deactivated account.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Activates a currently deactivated account. Used to finalize account migration after the account''s repo is imported and identity is setup.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.checkAccountStatus:
    get:
      operationId: serverCheckAccountStatus
      summary: Bluesky Returns the status of an account, especially as pertaining to import or recovery.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        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.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - activated
                - validDid
                - repoCommit
                - repoRev
                - repoBlocks
                - indexedRecords
                - privateStateValues
                - expectedBlobs
                - importedBlobs
                properties:
                  activated:
                    type: boolean
                  validDid:
                    type: boolean
                  repoCommit:
                    type: string
                    format: cid
                  repoRev:
                    type: string
                  repoBlocks:
                    type: integer
                  indexedRecords:
                    type: integer
                  privateStateValues:
                    type: integer
                  expectedBlobs:
                    type: integer
                  importedBlobs:
                    type: integer
              examples:
                ServerCheckAccountStatusResponse200Example:
                  $ref: '#/components/examples/ServerCheckAccountStatusResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.confirmEmail:
    post:
      operationId: serverConfirmEmail
      summary: Bluesky Confirm an email using a token from com.atproto.server.requestEmailConfirmation.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Confirm an email using a token from com.atproto.server.requestEmailConfirmation.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - token
              properties:
                email:
                  type: string
                token:
                  type: string
            examples:
              ServerConfirmEmailRequestExample:
                $ref: '#/components/examples/ServerConfirmEmailRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - AccountNotFound
                    - ExpiredToken
                    - InvalidToken
                    - InvalidEmail
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.createAccount:
    post:
      operationId: serverCreateAccount
      summary: Bluesky Create an account.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Create an account. Implemented by PDS.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - handle
              properties:
                email:
                  type: string
                handle:
                  type: string
                  description: Requested handle for the account.
                  format: handle
                did:
                  type: string
                  description: Pre-existing atproto DID, being imported to a new account.
                  format: did
                inviteCode:
                  type: string
                verificationCode:
                  type: string
                verificationPhone:
                  type: string
                password:
                  type: string
                  description: Initial account password. May need to meet instance-specific password strength requirements.
                recoveryKey:
                  type: string
                  description: DID PLC rotation key (aka, recovery key) to be included in PLC creation operation.
                plcOp: {}
            examples:
              ServerCreateAccountRequestExample:
                $ref: '#/components/examples/ServerCreateAccountRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Account login session returned on successful account creation.
                required:
                - accessJwt
                - refreshJwt
                - handle
                - did
                properties:
                  accessJwt:
                    type: string
                  refreshJwt:
                    type: string
                  handle:
                    type: string
                    format: handle
                  did:
                    type: string
                    description: The DID of the new account.
                    format: did
                  didDoc: {}
              examples:
                ServerCreateAccountResponse200Example:
                  $ref: '#/components/examples/ServerCreateAccountResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - InvalidHandle
                    - InvalidPassword
                    - InvalidInviteCode
                    - HandleNotAvailable
                    - UnsupportedDomain
                    - UnresolvableDid
                    - IncompatibleDidDoc
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.createAppPassword:
    post:
      operationId: serverCreateAppPassword
      summary: Bluesky Create an App Password.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Create an App Password.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: A short name for the App Password, to help distinguish them.
                privileged:
                  type: boolean
                  description: If an app password has 'privileged' access to possibly sensitive account state. Meant for use with trusted clients.
            examples:
              ServerCreateAppPasswordRequestExample:
                $ref: '#/components/examples/ServerCreateAppPasswordRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComAtprotoServerCreateAppPasswordAppPassword'
              examples:
                ServerCreateAppPasswordResponse200Example:
                  $ref: '#/components/examples/ServerCreateAppPasswordResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - AccountTakedown
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.createInviteCode:
    post:
      operationId: serverCreateInviteCode
      summary: Bluesky Create an invite code.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Create an invite code.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - useCount
              properties:
                useCount:
                  type: integer
                forAccount:
                  type: string
                  format: did
            examples:
              ServerCreateInviteCodeRequestExample:
                $ref: '#/components/examples/ServerCreateInviteCodeRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                properties:
                  code:
                    type: string
              examples:
                ServerCreateInviteCodeResponse200Example:
                  $ref: '#/components/examples/ServerCreateInviteCodeResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.createInviteCodes:
    post:
      operationId: serverCreateInviteCodes
      summary: Bluesky Create invite codes.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Create invite codes.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - codeCount
              - useCount
              properties:
                codeCount:
                  type: integer
                  default: 1
                useCount:
                  type: integer
                forAccounts:
                  type: array
                  items:
                    type: string
                    format: did
            examples:
              ServerCreateInviteCodesRequestExample:
                $ref: '#/components/examples/ServerCreateInviteCodesRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - codes
                properties:
                  codes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ComAtprotoServerCreateInviteCodesAccountCodes'
              examples:
                ServerCreateInviteCodesResponse200Example:
                  $ref: '#/components/examples/ServerCreateInviteCodesResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.createSession:
    post:
      operationId: serverCreateSession
      summary: Bluesky Create an authentication session.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Create an authentication session.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - password
              properties:
                identifier:
                  type: string
                  description: Handle or other identifier supported by the server for the authenticating user.
                password:
                  type: string
                authFactorToken:
                  type: string
            examples:
              ServerCreateSessionRequestExample:
                $ref: '#/components/examples/ServerCreateSessionRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - accessJwt
                - refreshJwt
                - handle
                - did
                properties:
                  accessJwt:
                    type: string
                  refreshJwt:
                    type: string
                  handle:
                    type: string
                    format: handle
                  did:
                    type: string
                    format: did
                  didDoc: {}
                  email:
                    type: string
                  emailConfirmed:
                    type: boolean
                  emailAuthFactor:
                    type: boolean
                  active:
                    type: boolean
                  status:
                    type: string
                    description: 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.
                    enum:
                    - takendown
                    - suspended
                    - deactivated
              examples:
                ServerCreateSessionResponse200Example:
                  $ref: '#/components/examples/ServerCreateSessionResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - AccountTakedown
                    - AuthFactorTokenRequired
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.deactivateAccount:
    post:
      operationId: serverDeactivateAccount
      summary: Bluesky Deactivates a currently active account.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        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.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deleteAfter:
                  type: string
                  description: A recommendation to server as to how long they should hold onto the deactivated account before deleting.
                  format: date-time
            examples:
              ServerDeactivateAccountRequestExample:
                $ref: '#/components/examples/ServerDeactivateAccountRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.deleteAccount:
    post:
      operationId: serverDeleteAccount
      summary: Bluesky Delete an actor's account with a token and password.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Delete an actor''s account with a token and password. Can only be called after requesting a deletion token. Requires auth.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - did
              - password
              - token
              properties:
                did:
                  type: string
                  format: did
                password:
                  type: string
                token:
                  type: string
            examples:
              ServerDeleteAccountRequestExample:
                $ref: '#/components/examples/ServerDeleteAccountRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.deleteSession:
    post:
      operationId: serverDeleteSession
      summary: Bluesky Delete the current session.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Delete the current session. Requires auth.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/com.atproto.server.describeServer:
    get:
      operationId: serverDescribeServer
      summary: Bluesky Describes the server's account creation requirements and capabilities.
      description: '*This endpoint is part of the atproto PDS server and account management APIs. Requests often require authentication and are made directly to the user''s own PDS instance.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Describes the server''s account creation requirements and capabilities. Implemented by PDS.'
      tags:
      - Server
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - did
                - availableUserDomains
                properties:
                  inviteCodeRequired:
                    type: boolean
                    description: If true, an invite code must be supplied to create an account on this instance.
                  phoneVerificationRequired:
                    type: boolean
                    description: If true, a phone verification token must be supplied to create an account on this instance.
                  availableUserDomains:
                    type: array
                    items:
                      type: string
                  links:
                    $ref: '#/components/schemas/ComAtprotoServerDescribeServerLinks'
                  contact:
                    $ref: '#/components/schemas/ComAtpr

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bluesky/refs/heads/main/openapi/bluesky-server-api-openapi.yml