X Direct Messages API

openapi: 3.2.0
info:
  description: X API v2 core endpoints
  version: '2.168'
  title: X API v2 Direct Messages 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: Direct Messages
  description: Endpoints related to retrieving, managing Direct Messages
  externalDocs:
    description: Find out more
    url: https://docs.x.com/x-api/direct-messages/introduction
paths:
  /2/dm_conversations:
    post:
      security:
      - OAuth2UserToken:
        - dm.write
        - users.read
        - tweet.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Create DM conversation
      description: Initiates a new direct message conversation with specified participants.
      operationId: createDirectMessagesConversation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectMessagesConversationRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDirectMessagesConversationResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/dm_conversations/media/{dm_id}/{media_id}/{resource_id}:
    get:
      security:
      - OAuth2UserToken:
        - dm.read
      tags:
      - Direct Messages
      summary: Download DM Media
      description: Downloads media attached to a legacy Direct Message. The requesting user must be a participant in the conversation containing the specified DM event. The response body contains raw binary bytes.
      operationId: dmConversationsMediaDownload
      parameters:
      - name: dm_id
        in: path
        required: true
        schema:
          type: string
        style: simple
      - name: media_id
        in: path
        required: true
        schema:
          type: string
        style: simple
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
        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/dm_conversations/with/{participant_id}/dm_events:
    get:
      security:
      - OAuth2UserToken:
        - users.read
        - dm.read
        - tweet.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Get Direct Messages Events by Participant ID
      operationId: getDirectMessagesEventsByParticipantId
      parameters:
      - name: participant_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
      - name: pagination_token
        in: query
        description: A base32hex-encoded pagination token.
        required: false
        schema:
          type: string
          minLength: 16
        style: form
      - name: event_types
        in: query
        required: false
        schema:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
            - MessageCreate
            - ParticipantsJoin
            - ParticipantsLeave
          default:
          - MessageCreate
          - ParticipantsLeave
          - ParticipantsJoin
        explode: false
        style: form
      - $ref: '#/components/parameters/DmEventFieldsParameter'
      - $ref: '#/components/parameters/DmEventExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/PostFieldsParameter'
      - $ref: '#/components/parameters/MediaFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDirectMessagesEventsByParticipantIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/dm_conversations/with/{participant_id}/messages:
    post:
      security:
      - OAuth2UserToken:
        - users.read
        - dm.write
        - tweet.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Create DM message by participant ID
      description: Sends a new direct message to a specific participant by their ID.
      operationId: createDirectMessagesByParticipantId
      parameters:
      - name: participant_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectMessagesByParticipantIdRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDirectMessagesByParticipantIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/dm_conversations/{dm_conversation_id}/messages:
    post:
      security:
      - OAuth2UserToken:
        - users.read
        - tweet.read
        - dm.write
      - UserToken: []
      tags:
      - Direct Messages
      summary: Create Direct Messages by Conversation ID
      operationId: createDirectMessagesByConversationId
      parameters:
      - name: dm_conversation_id
        in: path
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectMessagesByConversationIdRequest'
        required: true
      responses:
        '201':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDirectMessagesByConversationIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/dm_conversations/{id}/dm_events:
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - dm.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Get Direct Messages Events by Conversation ID
      operationId: getDirectMessagesEventsByConversationId
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^([0-9]{1,19}-[0-9]{1,19}|[0-9]{15,19})$
        style: simple
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
      - name: pagination_token
        in: query
        description: A base32hex-encoded pagination token.
        required: false
        schema:
          type: string
          minLength: 16
        style: form
      - name: event_types
        in: query
        required: false
        schema:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
            - MessageCreate
            - ParticipantsJoin
            - ParticipantsLeave
          default:
          - MessageCreate
          - ParticipantsLeave
          - ParticipantsJoin
        explode: false
        style: form
      - $ref: '#/components/parameters/DmEventFieldsParameter'
      - $ref: '#/components/parameters/DmEventExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/PostFieldsParameter'
      - $ref: '#/components/parameters/MediaFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDirectMessagesEventsByConversationIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/dm_events:
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - dm.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Get Direct Messages Events
      operationId: getDirectMessagesEvents
      parameters:
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
      - name: pagination_token
        in: query
        description: A base32hex-encoded pagination token.
        required: false
        schema:
          type: string
          minLength: 16
        style: form
      - name: event_types
        in: query
        required: false
        schema:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
            - MessageCreate
            - ParticipantsJoin
            - ParticipantsLeave
          default:
          - MessageCreate
          - ParticipantsLeave
          - ParticipantsJoin
        explode: false
        style: form
      - $ref: '#/components/parameters/DmEventFieldsParameter'
      - $ref: '#/components/parameters/DmEventExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/PostFieldsParameter'
      - $ref: '#/components/parameters/MediaFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDirectMessagesEventsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/dm_events/{event_id}:
    delete:
      security:
      - OAuth2UserToken:
        - dm.write
        - dm.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Delete DM event
      description: Deletes a specific direct message event by its ID, if owned by the authenticated user.
      operationId: deleteDirectMessagesEvents
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDirectMessagesEventsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - dm.read
        - users.read
      - UserToken: []
      tags:
      - Direct Messages
      summary: Get Direct Messages Events by ID
      operationId: getDirectMessagesEventsById
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9]{1,19}$
        style: simple
      - $ref: '#/components/parameters/DmEventFieldsParameter'
      - $ref: '#/components/parameters/DmEventExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/PostFieldsParameter'
      - $ref: '#/components/parameters/MediaFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDirectMessagesEventsByIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    DeleteDirectMessagesEventsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DeleteDirectMessagesEventsResponseData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    PostPublicMetrics:
      type: object
      description: Engagement metrics for the Post at the time of the request.
      required:
      - repost_count
      - reply_count
      - like_count
      - quote_count
      - bookmark_count
      - impression_count
      properties:
        bookmark_count:
          type: integer
          description: Number of times this Post has been bookmarked.
          format: int64
        impression_count:
          type: integer
          description: Number of times this Post has been viewed.
          format: int64
        like_count:
          type: integer
          description: Number of likes on this Post.
          format: int64
        quote_count:
          type: integer
          description: Number of quote Posts of this Post.
          format: int64
        reply_count:
          type: integer
          description: Number of replies to this Post.
          format: int64
        repost_count:
          type: integer
          description: Number of times this Post has been reposted.
          format: int64
    PostDisplayTextRange:
      type: array
      description: The inclusive start and exclusive end indices of the displayable content of the Post.
      minItems: 2
      maxItems: 2
      items:
        type: integer
        format: int64
    Expansions:
      type: object
      properties:
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        places:
          type: array
          items:
            $ref: '#/components/schemas/Place'
        polls:
          type: array
          items:
            $ref: '#/components/schemas/Poll'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Media:
      type: object
      properties:
        alt_text:
          type: string
        duration_ms:
          type: integer
        height:
          type: integer
        media_key:
          type: string
        non_public_metrics:
          $ref: '#/components/schemas/MediaNonPublicMetrics'
        organic_metrics:
          $ref: '#/components/schemas/MediaOrganicMetrics'
        preview_image_url:
          type: string
        promoted_metrics:
          $ref: '#/components/schemas/MediaPromotedMetrics'
        public_metrics:
          $ref: '#/components/schemas/MediaPublicMetrics'
        type:
          type: string
        url:
          type: string
        variants:
          $ref: '#/components/schemas/MediaVariants'
        width:
          type: integer
    GetDirectMessagesEventsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DmEvent'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
        meta:
          type: object
          properties:
            next_token:
              type: string
              description: Pagination token for the next page of results.
            previous_token:
              type: string
              description: Pagination token for the previous page of results.
            result_count:
              type: integer
              description: Number of items in the data array.
              format: int32
    CreateDirectMessagesByParticipantIdAttachments:
      type: object
      required:
      - media_id
      properties:
        media_id:
          type: string
          description: A media id to attach to the message.
          pattern: ^[0-9]{1,19}$
      additionalProperties: false
    CreateDirectMessagesConversationMessage:
      type: object
      properties:
        attachments:
          type: array
          description: Attachments to include with the message.
          items:
            $ref: '#/components/schemas/CreateDirectMessagesConversationMessageAttachments'
        text:
          type: string
          description: Text of the Direct Message.
          minLength: 1
      additionalProperties: false
    CreateDirectMessagesByConversationIdAttachments:
      type: object
      required:
      - media_id
      properties:
        media_id:
          type: string
          description: A media id to attach to the message.
          pattern: ^[0-9]{1,19}$
      additionalProperties: false
    PostGeo:
      type: object
      description: The location tagged on the Post, if the user provided one.
      properties:
        coordinates:
          type:
          - object
          - 'null'
          description: A GeoJSON Point geometry.
          required:
          - type
          - coordinates
          properties:
            coordinates:
              type: array
              description: '[longitude, latitude].'
              minItems: 2
              maxItems: 2
              items:
                type: number
                format: double
            type:
              type: string
              description: The GeoJSON geometry type.
              enum:
              - Point
        place_id:
          type:
          - string
          - 'null'
          description: The unique identifier of the tagged place.
    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
    CreateDirectMessagesByConversationIdRequest:
      anyOf:
      - required:
        - text
      - required:
        - attachments
      type: object
      description: At least one of `text`, `attachments` is required.
      properties:
        attachments:
          type: array
          description: Attachments to include with the message.
          items:
            $ref: '#/components/schemas/CreateDirectMessagesByConversationIdAttachments'
        text:
          type: string
          description: Text of the Direct Message.
          minLength: 1
      additionalProperties: false
    CreateDirectMessagesConversationResponseData:
      type: object
      required:
      - dm_conversation_id
      - dm_event_id
      properties:
        dm_conversation_id:
          type: string
          description: The id of the created conversation.
        dm_event_id:
          type: string
          description: The id of the created DM event.
    CreateDirectMessagesByParticipantIdResponseData:
      type: object
      required:
      - dm_conversation_id
      - dm_event_id
      properties:
        dm_conversation_id:
          type: string
          description: The conversation the message was sent to.
        dm_event_id:
          type: string
          description: The id of the created DM event.
    PostSuggestedSourceLinks:
      type: array
      description: URLs suggested as sources for this Post.
      items:
        type: string
    NotAuthorizedForResourceProblem:
      type: object
      required:
      - type
      - title
      - detail
      - resource_type
      properties:
        detail:
          type: string
        parameter:
          type: string
        resource_id:
          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/not-authorized-for-resource
        value:
          type: string
    DmEventAttachments:
      type: object
      description: Media and card attachments present in this Direct Message event.
      properties:
        card_ids:
          type:
          - array
          - 'null'
          description: IDs of cards attached to this Direct Message.
          items:
            type: string
        media_keys:
          type:
          - array
          - 'null'
          description: Media keys of media (including audio) attached to this Direct Message.
          items:
            type: string
    CreateDirectMessagesConversationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateDirectMessagesConversationResponseData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    PostEntities:
      type: object
      description: A list of metadata entities (hashtags, mentions, URLs) found in the Post text.
      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
            properties:
              end:
                type: integer
                format: int64
              id:
                type:
                - string
                - 'null'
              start:
                type: integer
                format: int64
              username:
                type:
                - string
                - 'null'
        urls:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A URL entity found in the Post text, enriched with link metadata.
            required:
            - start
            - end
            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
                format: int64
              status:
                type:
                - integer
                - 'null'
                description: HTTP status from resolving the URL.
                format: int64
              title:
                type:
                - string
                - 'null'
                description: Title of the linked page, when available.
              unwound_url:
                type:
                - string
                - 'null'
                description: The final destination after following redirects.
              url:
                type:
                - string
                - 'null'
                description: The t.co shortened URL.
    MediaVariants:
      type: array
      description: Each media object may have multiple display or playback variants, with different resolutions or formats.
      items:
        type: object
        description: A single playback or display variant of a media object.
        properties:
          bit_rate:
            type:
            - integer
            - 'null'
            description: The bit rate of this variant, in bits per second. Absent for playlist variants.
            format: int64
          content_type:
            type:
            - string
            - 'null'
            description: The MIME type of this variant, for example "video/mp4" or "application/x-mpegURL".
          url:
            type:
            - string
            - 'null'
            description: The URL to this media variant.
    PostReferencedPosts:
      type: array
      description: A list of Posts this Post refers to. If the Post is a Retweet, Quote or Reply, it includes the referenced Post's type and ID.
      items:
        type: object
        description: A reference from this Post to another Post (repost, quote, or reply).
        required:
        - type
        - id
        properties:
          id:
            type: string
            description: Unique identifier of the referenced Post.
          type:
            description: How this Post references the other Post.
            oneOf:
            - type: string
              description: The kind of Post-to-Post reference.
              enum:
              - retweeted
              - quoted
              - replied_to
    CreateDirectMessagesByParticipantIdResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateDirectMessagesByParticipantIdResponseData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
    CreateDirectMessagesByParticipantIdRequest:
      anyOf:
      - required:
        - text
      - required:
        - attachments
      type: object
      description: At least one of `text`, `attachments` is required.
      properties:
        attachments:
          type: array
          description: Attachments to include with the message.
          items:
            $ref: '#/components/schemas/CreateDirectMessagesByParticipantIdAttachments'
        text:
          type: string
          description: Text of the Direct Message.
          minLength: 1
      additionalProperties: false
    MediaNonPublicMetrics:
      type: object
      description: Nonpublic engagement metrics for the media at the time of the request.
      properties:
        playback_0_count:
          type:
          - integer
          - 'null'
          description: Number of users who started playback (0% quartile) of this video.
          format: int64
        playback_100_count:
          type:
          - integer
          - 'null'
          description: Number of users who completed playback (100% quartile) of this video.
          format: int64
        playback_25_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 25% of this video.
          format: int64
        playback_50_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 50% of this video.
          format: int64
        playback_75_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 75% of this video.
          format: int64
    UserConnectionStatus:
      type: array
      description: Returns detailed information about the relationship between two users.
      items:
        type: string
        description: A connection between the authenticated User and this User.
        enum:
        - blocking
        - follow_request_received
        - follow_request_sent
        - followed_by
        - following
        - muting
    GetDirectMessagesEventsByConversationIdResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DmEvent'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
        meta:
          type: object
          properties:
            next_token:
              type: string
              description: Pagination token for the next page of results.
            previous_token:
              type: string
              description: Pagination token for the previous page of results.
            res

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