X Chat API

openapi: 3.2.0
info:
  description: X API v2 core endpoints
  version: '2.168'
  title: X API v2 Chat API
  termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
  contact:
    name: X Developers
    url: https://developer.x.com/
  license:
    name: X Developer Agreement and Policy
    url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
  url: https://api.x.com
tags:
- name: Chat
  description: Endpoints related to Chat encrypted messaging
  externalDocs:
    description: Find out more
    url: https://developer.x.com/
paths:
  /2/chat/conversations:
    get:
      security:
      - OAuth2UserToken:
        - dm.read
        - users.read
      - UserToken: []
      tags:
      - Chat
      summary: Get Chat Conversations
      description: Retrieves a list of Chat conversations for the authenticated user's inbox.
      externalDocs:
        url: https://developer.x.com/
      operationId: getChatConversations
      parameters:
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 10
        style: form
      - name: pagination_token
        in: query
        required: false
        schema:
          type: string
        style: form
      - $ref: '#/components/parameters/ChatConversationFieldsParameter'
      - $ref: '#/components/parameters/ChatConversationExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChatConversationsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/group:
    post:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - dm.write
      - UserToken: []
      tags:
      - Chat
      summary: Create Chat Group Conversation
      description: Creates a new encrypted Chat group conversation on behalf of the authenticated user.
      externalDocs:
        url: https://developer.x.com/
      operationId: createChatConversation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatConversationRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatConversationResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/group/initialize:
    post:
      security:
      - OAuth2UserToken:
        - dm.write
      - UserToken: []
      tags:
      - Chat
      summary: Initialize Chat Group
      description: Initializes a new Chat group conversation and returns a unique conversation ID. Use the returned conversation_id in a subsequent POST /chat/conversations/group call to fully create and configure the group.
      externalDocs:
        url: https://developer.x.com/
      operationId: initializeChatGroup
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializeChatGroupResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}:
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - dm.read
      - UserToken: []
      tags:
      - Chat
      summary: Get Chat Conversation
      description: Returns metadata for a Chat conversation including type, muted status, and group details. Use chat_conversation.fields to select which fields are returned. Use expansions to hydrate member, admin, or participant user objects. Use user.fields to control which profile fields are returned for expanded users.
      externalDocs:
        url: https://developer.x.com/
      operationId: getChatConversation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        style: simple
      - $ref: '#/components/parameters/ChatConversationFieldsParameter'
      - $ref: '#/components/parameters/ChatConversationExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChatConversationResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/events:
    get:
      security:
      - OAuth2UserToken:
        - dm.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Chat
      summary: Get Chat Conversation Events
      description: Retrieves messages and key change events for a specific Chat conversation with pagination support. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.
      externalDocs:
        url: https://developer.x.com/
      operationId: getChatConversationEvents
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 10
        style: form
      - name: pagination_token
        in: query
        required: false
        schema:
          type: string
        style: form
      - $ref: '#/components/parameters/ChatMessageEventFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChatConversationEventsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/keys:
    post:
      security:
      - OAuth2UserToken:
        - users.read
        - dm.write
        - tweet.read
      - UserToken: []
      tags:
      - Chat
      summary: Add Conversation Keys
      description: Adds (initializes or rotates) the encryption keys for a Chat conversation. Call this before sending messages in a new 1:1 conversation, and again with a newer key version to rotate the conversation key. For 1:1 conversations, provide the recipient's user ID as the conversation id; the server constructs the canonical conversation ID from the authenticated user and recipient. The request body must contain the conversation key version and participant keys (the conversation key encrypted for each participant using their public key).
      externalDocs:
        url: https://developer.x.com/
      operationId: addConversationKeys
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddConversationKeysRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddConversationKeysResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/members:
    post:
      security:
      - OAuth2UserToken:
        - users.read
        - tweet.read
        - dm.write
      - UserToken: []
      tags:
      - Chat
      summary: Add members to a Chat group conversation
      description: Adds one or more members to an existing encrypted Chat group conversation, rotating the conversation key.
      externalDocs:
        url: https://developer.x.com/
      operationId: addChatGroupMembers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddChatGroupMembersRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddChatGroupMembersResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/messages:
    post:
      security:
      - OAuth2UserToken:
        - dm.write
        - users.read
        - tweet.read
      - UserToken: []
      tags:
      - Chat
      summary: Send Chat Message
      description: Sends an encrypted message to a specific Chat conversation. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.
      externalDocs:
        url: https://developer.x.com/
      operationId: sendChatMessage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendChatMessageRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendChatMessageResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/messages/delete:
    post:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - dm.write
      - UserToken: []
      tags:
      - Chat
      summary: Delete Chat messages
      description: Deletes one or more messages from a Chat conversation. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient. Delete for all removes a message you sent (or, in groups you administer, any message) for every participant; delete for self removes any message only from your own view.
      externalDocs:
        url: https://developer.x.com/
      operationId: deleteChatMessages
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteChatMessagesRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteChatMessagesResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/read:
    post:
      security:
      - OAuth2UserToken:
        - tweet.read
        - dm.write
        - users.read
      - UserToken: []
      tags:
      - Chat
      summary: Mark Conversation as Read
      description: Marks a specific Chat conversation as read on behalf of the authenticated user. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.
      externalDocs:
        url: https://developer.x.com/
      operationId: markChatConversationRead
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkChatConversationReadRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkChatConversationReadResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/conversations/{id}/typing:
    post:
      security:
      - OAuth2UserToken:
        - tweet.read
        - dm.write
        - users.read
      - UserToken: []
      tags:
      - Chat
      summary: Send Typing Indicator
      description: Sends a typing indicator to a specific Chat conversation on behalf of the authenticated user. For 1:1 conversations, provide the recipient's user ID; the server constructs the canonical conversation ID from the authenticated user and recipient.
      externalDocs:
        url: https://developer.x.com/
      operationId: sendChatTypingIndicator
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendChatTypingIndicatorResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/media/upload/initialize:
    post:
      security:
      - OAuth2UserToken:
        - media.write
      - UserToken: []
      tags:
      - Chat
      summary: Initialize Chat Media Upload
      description: Initializes an XChat media upload session.
      externalDocs:
        url: https://docs.x.com/x-api/media/media-upload
      operationId: chatMediaUploadInitialize
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatMediaUploadInitializeRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMediaUploadInitializeResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/media/upload/{id}/append:
    post:
      security:
      - OAuth2UserToken:
        - media.write
      - UserToken: []
      tags:
      - Chat
      summary: Append Chat Media Upload
      description: Appends media data to an XChat upload session.
      externalDocs:
        url: https://docs.x.com/x-api/media/media-upload
      operationId: chatMediaUploadAppend
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatMediaUploadAppendRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ChatMediaUploadAppendRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMediaUploadAppendResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/media/upload/{id}/finalize:
    post:
      security:
      - OAuth2UserToken:
        - media.write
      - UserToken: []
      tags:
      - Chat
      summary: Finalize Chat Media Upload
      description: Finalizes an XChat media upload session.
      externalDocs:
        url: https://docs.x.com/x-api/media/media-upload
      operationId: chatMediaUploadFinalize
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatMediaUploadFinalizeRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMediaUploadFinalizeResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/chat/media/{id}/{media_hash_key}:
    get:
      security:
      - OAuth2UserToken:
        - media.write
      - UserToken: []
      tags:
      - Chat
      summary: Download Chat Media
      description: Downloads encrypted media bytes from an XChat conversation. The response body contains raw binary bytes.
      operationId: chatMediaDownload
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}|[0-9]{1,19}-[0-9]{1,19}|g[0-9]{1,19})$
        style: simple
      - name: media_hash_key
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,50}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/users/{id}/public_keys:
    post:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - dm.write
      - UserToken: []
      tags:
      - Chat
      summary: Add public key
      description: Registers a user's public key for X Chat encryption.
      externalDocs:
        url: https://developer.x.com/
      operationId: addUserPublicKey
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserId'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUserPublicKeyRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddUserPublicKeyResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    AddConversationKeysActionSignaturesMessageEventSignature:
      type: object
      required:
      - signature
      - public_key_version
      - signature_version
      properties:
        message_signing_key_info_list:
          type: array
          description: List of signing key information for message verification.
          items:
            $ref: '#/components/schemas/AddConversationKeysActionSignaturesMessageEventSignatureMessageSigningKeyInfoList'
        public_key_version:
          type: string
          description: The version of the public key used for signing.
          pattern: ^[0-9]+$
        signature:
          type: string
          description: The signature of the message event.
          minLength: 1
          pattern: ^[A-Za-z0-9+/=_-]+$
        signature_version:
          type: string
          description: The version of the signature algorithm.
          pattern: ^[0-9]+$
        signing_public_key:
          type: string
          description: The public key used for signing.
    FieldHydrationFailureProblem:
      type: object
      required:
      - type
      - title
      - detail
      - field
      properties:
        detail:
          type: string
        field:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/field-hydration-failure
    CreateChatConversationActionSignatures:
      type: object
      required:
      - message_id
      - encoded_message_event_detail
      - message_event_signature
      properties:
        encoded_message_event_detail:
          type: string
          description: Base64-encoded message event detail.
          minLength: 1
          pattern: ^[A-Za-z0-9+/=_-]+$
        message_event_signature:
          description: Message event signature supplied with an action signature.
          $ref: '#/components/schemas/CreateChatConversationActionSignaturesMessageEventSignature'
        message_id:
          type: string
          description: Client-generated ID of the message being signed.
          minLength: 1
        signature_payload:
          type: string
          description: Payload string the client signed; used only in server-side failure logs.
    DeleteChatMessagesActionSignaturesMessageEventSignature:
      type: object
      required:
      - signature
      - public_key_version
      - signature_version
      properties:
        message_signing_key_info_list:
          type: array
          description: List of signing key information for message verification.
          items:
            $ref: '#/components/schemas/DeleteChatMessagesActionSignaturesMessageEventSignatureMessageSigningKeyInfoList'
        public_key_version:
          type: string
          description: The version of the public key used for signing.
          pattern: ^[0-9]+$
        signature:
          type: string
          description: The signature of the message event.
          minLength: 1
          pattern: ^[A-Za-z0-9+/=_-]+$
        signature_version:
          type: string
          description: The version of the signature algorithm.
          pattern: ^[0-9]+$
        signing_public_key:
          type: string
          description: The public key used for signing.
    Poll:
      type: object
      properties:
        duration_minutes:
          type: integer
        end_datetime:
          type: string
        id:
          type: string
        options:
          $ref: '#/components/schemas/PollOptions'
        voting_status:
          type: string
    UserWithheld:
      type: object
      description: Withholding details for withheld content.
      properties:
        country_codes:
          type:
          - array
          - 'null'
          description: A list of countries (as ISO 3166-1 alpha-2 codes) where this content is withheld.
          items:
            type: string
        scope:
          type:
          - string
          - 'null'
          description: The scope of the withholding. Only present, with the value "user", when the entire User is withheld.
          enum:
          - user
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    ResourceUnavailableProblem:
      type: object
      required:
      - type
      - title
      - detail
      - resource_type
      properties:
        detail:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/resource-unavailable
    MarkChatConversationReadResponseData:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the conversation was marked read.
    AddChatGroupMembersActionSignaturesMessageEventSignatureMessageSigningKeyInfoList:
      type: object
      properties:
        member_id:
          type: string
          description: The member ID associated with this signing key.
        public_key_version:
          type: string
          description: The version of the public key.
        signing_public_key:
          type: string
          description: The signing public key.
    UserEntities:
      type: object
      description: A list of metadata found in the User's profile description.
      properties:
        description:
          type:
          - object
          - 'null'
          description: Entities found in the User's bio.
          properties:
            cashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
                    type: integer
                    description: End index in the text (exclusive).
                    format: int64
                  start:
                    type: integer
                    description: Start index in the text (inclusive).
                    format: int64
                  tag:
                    type: string
            hashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
                    type: integer
                    description: End index in the text (exclusive).
                    format: int64
                  start:
                    type: integer
                    description: Start index in the text (inclusive).
                    format: int64
                  tag:
                    type: string
            mentions:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A user mention entity.
                required:
                - start
                - end
                - username
                properties:
                  end:
                    type: integer
                    format: int64
                  id:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
                    format: int64
                  username:
                    type: string
            urls:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A URL entity found in profile text.
                required:
                - start
                - end
                - url
                properties:
                  description:
                    type:
                    - string
                    - 'null'
                    description: Description of the linked page, when available.
                  display_url:
                    type:
                    - string
                    - 'null'
                    description: The URL as displayed in the Post text.
                  end:
                    type: integer
                    format: int64
                  expanded_url:
                    type:
                    - string
                    - 'null'
                    description: The fully resolved URL.
                  images:
                    type:
                    - array
                    - 'null'
                    items:
                      type: object
                      description: A preview image for a linked page.
                      properties:
                        height:
                          type:
                          - integer
                          - 'null'
                          format: int64
                        url:
                          type:
                          - string
                          - 'null'
                        width:
                          type:
                          - integer
                          - 'null'
                          format: int64
                  media_key:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
          

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