Bluesky Conversations API

openapi: 3.2.0
info:
  title: Bluesky Social Actor Profiles Conversations 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: Conversations
  description: Operations for managing direct message conversations.
paths:
  /xrpc/chat.bsky.convo.deleteMessageForSelf:
    post:
      operationId: chatConvoDeleteMessageForSelf
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - convoId
              - messageId
              properties:
                convoId:
                  type: string
                messageId:
                  type: string
            examples:
              ChatConvoDeleteMessageForSelfRequestExample:
                $ref: '#/components/examples/ChatConvoDeleteMessageForSelfRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatBskyConvoDefsDeletedMessageView'
              examples:
                ChatConvoDeleteMessageForSelfResponse200Example:
                  $ref: '#/components/examples/ChatConvoDeleteMessageForSelfResponse200Example'
        '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/chat.bsky.convo.getConvo:
    get:
      operationId: chatConvoGetConvo
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: convoId
        in: query
        required: true
        schema:
          type: string
        example: example-convoId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convo
                properties:
                  convo:
                    $ref: '#/components/schemas/ChatBskyConvoDefsConvoView'
              examples:
                ChatConvoGetConvoResponse200Example:
                  $ref: '#/components/examples/ChatConvoGetConvoResponse200Example'
        '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/chat.bsky.convo.getConvoForMembers:
    get:
      operationId: chatConvoGetConvoForMembers
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: members
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            format: did
          maxItems: 10
        example:
        - did:plc:example123abc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convo
                properties:
                  convo:
                    $ref: '#/components/schemas/ChatBskyConvoDefsConvoView'
              examples:
                ChatConvoGetConvoForMembersResponse200Example:
                  $ref: '#/components/examples/ChatConvoGetConvoForMembersResponse200Example'
        '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/chat.bsky.convo.getLog:
    get:
      operationId: chatConvoGetLog
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - logs
                properties:
                  cursor:
                    type: string
                  logs:
                    type: array
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/ChatBskyConvoDefsLogBeginConvo'
                      - $ref: '#/components/schemas/ChatBskyConvoDefsLogLeaveConvo'
                      - $ref: '#/components/schemas/ChatBskyConvoDefsLogCreateMessage'
                      - $ref: '#/components/schemas/ChatBskyConvoDefsLogDeleteMessage'
              examples:
                ChatConvoGetLogResponse200Example:
                  $ref: '#/components/examples/ChatConvoGetLogResponse200Example'
        '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/chat.bsky.convo.getMessages:
    get:
      operationId: chatConvoGetMessages
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: convoId
        in: query
        required: true
        schema:
          type: string
        example: example-convoId
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - messages
                properties:
                  cursor:
                    type: string
                  messages:
                    type: array
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/ChatBskyConvoDefsMessageView'
                      - $ref: '#/components/schemas/ChatBskyConvoDefsDeletedMessageView'
              examples:
                ChatConvoGetMessagesResponse200Example:
                  $ref: '#/components/examples/ChatConvoGetMessagesResponse200Example'
        '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/chat.bsky.convo.leaveConvo:
    post:
      operationId: chatConvoLeaveConvo
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - convoId
              properties:
                convoId:
                  type: string
            examples:
              ChatConvoLeaveConvoRequestExample:
                $ref: '#/components/examples/ChatConvoLeaveConvoRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convoId
                - rev
                properties:
                  convoId:
                    type: string
                  rev:
                    type: string
              examples:
                ChatConvoLeaveConvoResponse200Example:
                  $ref: '#/components/examples/ChatConvoLeaveConvoResponse200Example'
        '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/chat.bsky.convo.listConvos:
    get:
      operationId: chatConvoListConvos
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convos
                properties:
                  cursor:
                    type: string
                  convos:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatBskyConvoDefsConvoView'
              examples:
                ChatConvoListConvosResponse200Example:
                  $ref: '#/components/examples/ChatConvoListConvosResponse200Example'
        '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/chat.bsky.convo.muteConvo:
    post:
      operationId: chatConvoMuteConvo
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - convoId
              properties:
                convoId:
                  type: string
            examples:
              ChatConvoMuteConvoRequestExample:
                $ref: '#/components/examples/ChatConvoMuteConvoRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convo
                properties:
                  convo:
                    $ref: '#/components/schemas/ChatBskyConvoDefsConvoView'
              examples:
                ChatConvoMuteConvoResponse200Example:
                  $ref: '#/components/examples/ChatConvoMuteConvoResponse200Example'
        '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/chat.bsky.convo.sendMessage:
    post:
      operationId: chatConvoSendMessage
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - convoId
              - message
              properties:
                convoId:
                  type: string
                message:
                  $ref: '#/components/schemas/ChatBskyConvoDefsMessageInput'
            examples:
              ChatConvoSendMessageRequestExample:
                $ref: '#/components/examples/ChatConvoSendMessageRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatBskyConvoDefsMessageView'
              examples:
                ChatConvoSendMessageResponse200Example:
                  $ref: '#/components/examples/ChatConvoSendMessageResponse200Example'
        '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/chat.bsky.convo.sendMessageBatch:
    post:
      operationId: chatConvoSendMessageBatch
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/ChatBskyConvoSendMessageBatchBatchItem'
                  maxItems: 100
            examples:
              ChatConvoSendMessageBatchRequestExample:
                $ref: '#/components/examples/ChatConvoSendMessageBatchRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatBskyConvoDefsMessageView'
              examples:
                ChatConvoSendMessageBatchResponse200Example:
                  $ref: '#/components/examples/ChatConvoSendMessageBatchResponse200Example'
        '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/chat.bsky.convo.unmuteConvo:
    post:
      operationId: chatConvoUnmuteConvo
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - convoId
              properties:
                convoId:
                  type: string
            examples:
              ChatConvoUnmuteConvoRequestExample:
                $ref: '#/components/examples/ChatConvoUnmuteConvoRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convo
                properties:
                  convo:
                    $ref: '#/components/schemas/ChatBskyConvoDefsConvoView'
              examples:
                ChatConvoUnmuteConvoResponse200Example:
                  $ref: '#/components/examples/ChatConvoUnmuteConvoResponse200Example'
        '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/chat.bsky.convo.updateRead:
    post:
      operationId: chatConvoUpdateRead
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Conversations
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - convoId
              properties:
                convoId:
                  type: string
                messageId:
                  type: string
            examples:
              ChatConvoUpdateReadRequestExample:
                $ref: '#/components/examples/ChatConvoUpdateReadRequestExample'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - convo
                properties:
                  convo:
                    $ref: '#/components/schemas/ChatBskyConvoDefsConvoView'
              examples:
                ChatConvoUpdateReadResponse200Example:
                  $ref: '#/components/examples/ChatConvoUpdateReadResponse200Example'
        '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:
  schemas:
    ChatBskyConvoDefsMessageView:
      type: object
      required:
      - id
      - rev
      - text
      - sender
      - sentAt
      properties:
        id:
          type: string
        rev:
          type: string
        text:
          type: string
          maxLength: 10000
        facets:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyRichtextFacet'
        embed:
          oneOf:
          - $ref: '#/components/schemas/AppBskyEmbedReco

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