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