Bluesky Sync API

openapi: 3.1.0
info:
  title: Bluesky Social Actor Profiles Sync 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: Sync
  description: Operations for repository synchronization.
paths:
  /xrpc/com.atproto.sync.getBlob:
    get:
      operationId: syncGetBlob
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the account.
        required: true
        schema:
          type: string
          description: The DID of the account.
          format: did
        example: did:plc:example123abc
      - name: cid
        in: query
        description: The CID of the blob to fetch
        required: true
        schema:
          type: string
          description: The CID of the blob to fetch
          format: cid
        example: bafyreiabc123example
      responses:
        '200':
          description: OK
          content:
            '*/*': {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - BlobNotFound
                    - RepoNotFound
                    - RepoTakendown
                    - RepoSuspended
                    - RepoDeactivated
                  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.sync.getBlocks:
    get:
      operationId: syncGetBlocks
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the repo.
        required: true
        schema:
          type: string
          description: The DID of the repo.
          format: did
        example: did:plc:example123abc
      - name: cids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            format: cid
        example:
        - bafyreiabc123example
      responses:
        '200':
          description: OK
          content:
            application/vnd.ipld.car: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - BlockNotFound
                    - RepoNotFound
                    - RepoTakendown
                    - RepoSuspended
                    - RepoDeactivated
                  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.sync.getLatestCommit:
    get:
      operationId: syncGetLatestCommit
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Get the current commit CID & revision of the specified repo. Does not require auth.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the repo.
        required: true
        schema:
          type: string
          description: The DID of the repo.
          format: did
        example: did:plc:example123abc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - cid
                - rev
                properties:
                  cid:
                    type: string
                    format: cid
                  rev:
                    type: string
              examples:
                SyncGetLatestCommitResponse200Example:
                  $ref: '#/components/examples/SyncGetLatestCommitResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - RepoNotFound
                    - RepoTakendown
                    - RepoSuspended
                    - RepoDeactivated
                  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.sync.getRecord:
    get:
      operationId: syncGetRecord
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the repo.
        required: true
        schema:
          type: string
          description: The DID of the repo.
          format: did
        example: did:plc:example123abc
      - name: collection
        in: query
        required: true
        schema:
          type: string
          format: nsid
        example: app.bsky.feed.post
      - name: rkey
        in: query
        description: Record Key
        required: true
        schema:
          type: string
          description: Record Key
        example: example-rkey
      responses:
        '200':
          description: OK
          content:
            application/vnd.ipld.car: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - RecordNotFound
                    - RepoNotFound
                    - RepoTakendown
                    - RepoSuspended
                    - RepoDeactivated
                  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.sync.getRepo:
    get:
      operationId: syncGetRepo
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Download a repository export as CAR file. Optionally only a ''diff'' since a previous revision. Does not require auth; implemented by PDS.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the repo.
        required: true
        schema:
          type: string
          description: The DID of the repo.
          format: did
        example: did:plc:example123abc
      - name: since
        in: query
        description: The revision ('rev') of the repo to create a diff from.
        required: false
        schema:
          type: string
          description: The revision ('rev') of the repo to create a diff from.
        example: example-since
      responses:
        '200':
          description: OK
          content:
            application/vnd.ipld.car: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - RepoNotFound
                    - RepoTakendown
                    - RepoSuspended
                    - RepoDeactivated
                  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.sync.getRepoStatus:
    get:
      operationId: syncGetRepoStatus
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Get the hosting status for a repository, on this server. Expected to be implemented by PDS and Relay.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the repo.
        required: true
        schema:
          type: string
          description: The DID of the repo.
          format: did
        example: did:plc:example123abc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - did
                - active
                properties:
                  did:
                    type: string
                    format: did
                  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
                  rev:
                    type: string
                    description: Optional field, the current rev of the repo, if active=true
              examples:
                SyncGetRepoStatusResponse200Example:
                  $ref: '#/components/examples/SyncGetRepoStatusResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - RepoNotFound
                  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.sync.listBlobs:
    get:
      operationId: syncListBlobs
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        List blob CIDs for an account, since some repo revision. Does not require auth; implemented by PDS.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: did
        in: query
        description: The DID of the repo.
        required: true
        schema:
          type: string
          description: The DID of the repo.
          format: did
        example: did:plc:example123abc
      - name: since
        in: query
        description: Optional revision of the repo to list blobs since.
        required: false
        schema:
          type: string
          description: Optional revision of the repo to list blobs since.
        example: example-since
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 500
        example: 500
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - cids
                properties:
                  cursor:
                    type: string
                  cids:
                    type: array
                    items:
                      type: string
                      format: cid
              examples:
                SyncListBlobsResponse200Example:
                  $ref: '#/components/examples/SyncListBlobsResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                    - RepoNotFound
                    - RepoTakendown
                    - RepoSuspended
                    - RepoDeactivated
                  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.sync.listRepos:
    get:
      operationId: syncListRepos
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 500
        example: 500
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - repos
                properties:
                  cursor:
                    type: string
                  repos:
                    type: array
                    items:
                      $ref: '#/components/schemas/ComAtprotoSyncListReposRepo'
              examples:
                SyncListReposResponse200Example:
                  $ref: '#/components/examples/SyncListReposResponse200Example'
        '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.sync.notifyOfUpdate:
    post:
      operationId: syncNotifyOfUpdate
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - hostname
              properties:
                hostname:
                  type: string
                  description: Hostname of the current service (usually a PDS) that is notifying of update.
            examples:
              SyncNotifyOfUpdateRequestExample:
                $ref: '#/components/examples/SyncNotifyOfUpdateRequestExample'
      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.sync.requestCrawl:
    post:
      operationId: syncRequestCrawl
      summary: Bluesky This endpoint is part of the atproto repository synchronization APIs.
      description: 'This endpoint is part of the atproto repository synchronization APIs. Requests usually do not require authentication, and can be made to PDS intances or Relay instances.*


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


        Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.'
      tags:
      - Sync
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - hostname
              properties:
                hostname:
                  type: string
                  description: Hostname of the current service (eg, PDS) that is requesting to be crawled.
            examples:
              SyncRequestCrawlRequestExample:
                $ref: '#/components/examples/SyncRequestCrawlRequestExample'
      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
components:
  examples:
    SyncGetRepoStatusResponse200Example:
      summary: Successful response for syncGetRepoStatus
      value:
        did: did:plc:example123abc
        active: true
        status: takendown
        rev: example-rev
    SyncListReposResponse200Example:
      summary: Successful response for syncListRepos
      value:
        repos:
        - did: did:plc:example123abc
          head: bafyreiabc123example
          rev: example-rev
          active: true
          status: takendown
        cursor: eyJsYXN0SWQiOiIxMjM0NTYifQ
    SyncNotifyOfUpdateRequestExample:
      summary: Example request for syncNotifyOfUpdate
      value:
        hostname: Example Name
    SyncGetLatestCommitResponse200Example:
      summary: Successful response for syncGetLatestCommit
      value:
        cid: bafyreiabc123example
        rev: example-rev
    SyncListBlobsResponse200Example:
      summary: Successful response for syncListBlobs
      value:
        cids:
        - bafyreiabc123example
        cursor: eyJsYXN0SWQiOiIxMjM0NTYifQ
    SyncRequestCrawlRequestExample:
      summary: Example request for syncRequestCrawl
      value:
        hostname: Example Name
  schemas:
    ComAtprotoSyncListReposRepo:
      type: object
      required:
      - did
      - head
      - rev
      properties:
        did:
          type: string
          format: did
        head:
          type: string
          description: Current repo commit CID
          format: cid
        rev:
          type: string
        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
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer