Bluesky Identity API

openapi: 3.2.0
info:
  title: Bluesky Social Actor Profiles Identity 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: Identity
  description: Operations for identity management and DID resolution.
paths:
  /xrpc/com.atproto.identity.getRecommendedDidCredentials:
    get:
      operationId: identityGetRecommendedDidCredentials
      summary: Bluesky Describe the credentials that should be included in the DID doc of an account that is migrating t...
      description: '*To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Describe the credentials that should be included in the DID doc of an account that is migrating to this service.'
      tags:
      - Identity
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  rotationKeys:
                    type: array
                    items:
                      type: string
                  alsoKnownAs:
                    type: array
                    items:
                      type: string
                  verificationMethods: {}
                  services: {}
              examples:
                IdentityGetRecommendedDidCredentialsResponse200Example:
                  $ref: '#/components/examples/IdentityGetRecommendedDidCredentialsResponse200Example'
        '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.identity.requestPlcOperationSignature:
    post:
      operationId: identityRequestPlcOperationSignature
      summary: Bluesky Request an email with a code to in order to request a signed PLC operation.
      description: '*To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Request an email with a code to in order to request a signed PLC operation. Requires Auth.'
      tags:
      - Identity
      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.identity.resolveHandle:
    get:
      operationId: identityResolveHandle
      summary: Bluesky Resolves a handle (domain name) to a DID.
      description: '*To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Resolves a handle (domain name) to a DID.'
      tags:
      - Identity
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: handle
        in: query
        description: The handle to resolve.
        required: true
        schema:
          type: string
          description: The handle to resolve.
          format: handle
        example: user.bsky.social
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - did
                properties:
                  did:
                    type: string
                    format: did
              examples:
                IdentityResolveHandleResponse200Example:
                  $ref: '#/components/examples/IdentityResolveHandleResponse200Example'
        '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.identity.signPlcOperation:
    post:
      operationId: identitySignPlcOperation
      summary: Bluesky Signs a PLC operation to update some value(s) in the requesting DID's document.
      description: '*To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Signs a PLC operation to update some value(s) in the requesting DID''s document.'
      tags:
      - Identity
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: A token received through com.atproto.identity.requestPlcOperationSignature
                rotationKeys:
                  type: array
                  items:
                    type: string
                alsoKnownAs:
                  type: array
                  items:
                    type: string
                verificationMethods: {}
                services: {}
            examples:
              IdentitySignPlcOperationRequestExample:
                $ref: '#/components/examples/IdentitySignPlcOperationRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - operation
                properties:
                  operation: {}
              examples:
                IdentitySignPlcOperationResponse200Example:
                  $ref: '#/components/examples/IdentitySignPlcOperationResponse200Example'
        '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.identity.submitPlcOperation:
    post:
      operationId: identitySubmitPlcOperation
      summary: Bluesky Validates a PLC operation to ensure that it doesn't violate a service's constraints or get the id...
      description: '*To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Validates a PLC operation to ensure that it doesn''t violate a service''s constraints or get the identity into a bad state, then submits it to the PLC registry'
      tags:
      - Identity
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - operation
              properties:
                operation: {}
            examples:
              IdentitySubmitPlcOperationRequestExample:
                $ref: '#/components/examples/IdentitySubmitPlcOperationRequestExample'
      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.identity.updateHandle:
    post:
      operationId: identityUpdateHandle
      summary: Bluesky Updates the current account's handle.
      description: '*To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Updates the current account''s handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.'
      tags:
      - Identity
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - handle
              properties:
                handle:
                  type: string
                  description: The new handle.
                  format: handle
            examples:
              IdentityUpdateHandleRequestExample:
                $ref: '#/components/examples/IdentityUpdateHandleRequestExample'
      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:
    IdentityGetRecommendedDidCredentialsResponse200Example:
      summary: Successful response for identityGetRecommendedDidCredentials
      value:
        rotationKeys:
        - example-rotationKeys
        alsoKnownAs:
        - example-alsoKnownAs
        verificationMethods: {}
        services: {}
    IdentitySignPlcOperationResponse200Example:
      summary: Successful response for identitySignPlcOperation
      value:
        operation: {}
    IdentitySubmitPlcOperationRequestExample:
      summary: Example request for identitySubmitPlcOperation
      value:
        operation: {}
    IdentitySignPlcOperationRequestExample:
      summary: Example request for identitySignPlcOperation
      value:
        token: example-token
        rotationKeys:
        - example-rotationKeys
        alsoKnownAs:
        - example-alsoKnownAs
        verificationMethods: {}
        services: {}
    IdentityResolveHandleResponse200Example:
      summary: Successful response for identityResolveHandle
      value:
        did: did:plc:example123abc
    IdentityUpdateHandleRequestExample:
      summary: Example request for identityUpdateHandle
      value:
        handle: user.bsky.social
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer