Twitter/X Direct Messages API
Endpoints related to retrieving, managing Direct Messages
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/twitter-x-direct-messages-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
description: X API v2 available endpoints
version: '2.166'
title: X API v2 Account Activity 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://developer.twitter.com/en/docs/twitter-api/direct-messages
paths:
/2/dm_conversations:
post:
security:
- OAuth2UserToken:
- dm.write
- tweet.read
- users.read
- UserToken: []
tags:
- Direct Messages
summary: Create DM conversation
description: Initiates a new direct message conversation with specified participants.
operationId: createDirectMessagesConversation
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDmConversationRequest'
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDmEventResponse'
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.
externalDocs:
url: https://developer.x.com/
operationId: dmConversationsMediaDownload
parameters:
- name: dm_id
in: path
description: The unique identifier of the Direct Message event containing the media.
required: true
schema:
$ref: '#/components/schemas/DmEventId'
style: simple
- name: media_id
in: path
description: The unique identifier of the media attached to the Direct Message.
required: true
schema:
$ref: '#/components/schemas/MediaId'
style: simple
- name: resource_id
in: path
description: The resource identifier of the media file, including file extension (e.g. 'hVJQTwig.jpg').
required: true
schema:
$ref: '#/components/schemas/DmResourceId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/BinaryPayload'
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:
- dm.read
- tweet.read
- users.read
- UserToken: []
tags:
- Direct Messages
summary: Get DM events for a DM conversation
description: Retrieves direct message events for a specific conversation.
operationId: getDirectMessagesEventsByParticipantId
parameters:
- name: participant_id
in: path
description: The ID of the participant user for the One to One DM conversation.
required: true
schema:
$ref: '#/components/schemas/UserId'
style: simple
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationToken32'
style: form
- name: event_types
in: query
description: The set of event_types to include in the results.
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- MessageCreate
- ParticipantsJoin
- ParticipantsLeave
default:
- MessageCreate
- ParticipantsLeave
- ParticipantsJoin
example:
- MessageCreate
- ParticipantsLeave
explode: false
style: form
- $ref: '#/components/parameters/DmEventFieldsParameter'
- $ref: '#/components/parameters/DmEventExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2DmConversationsWithParticipantIdDmEventsResponse'
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:
- dm.write
- tweet.read
- users.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
description: The ID of the recipient user that will receive the DM.
required: true
schema:
$ref: '#/components/schemas/UserId'
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDmEventResponse'
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:
- dm.write
- tweet.read
- users.read
- UserToken: []
tags:
- Direct Messages
summary: Create DM message by conversation ID
description: Sends a new direct message to a specific conversation by its ID.
operationId: createDirectMessagesByConversationId
parameters:
- name: dm_conversation_id
in: path
description: The DM Conversation ID.
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDmEventResponse'
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:
- dm.read
- tweet.read
- users.read
- UserToken: []
tags:
- Direct Messages
summary: Get DM events for a DM conversation
description: Retrieves direct message events for a specific conversation.
operationId: getDirectMessagesEventsByConversationId
parameters:
- name: id
in: path
description: The DM conversation ID.
required: true
schema:
$ref: '#/components/schemas/DmConversationId'
style: simple
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationToken32'
style: form
- name: event_types
in: query
description: The set of event_types to include in the results.
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- MessageCreate
- ParticipantsJoin
- ParticipantsLeave
default:
- MessageCreate
- ParticipantsLeave
- ParticipantsJoin
example:
- MessageCreate
- ParticipantsLeave
explode: false
style: form
- $ref: '#/components/parameters/DmEventFieldsParameter'
- $ref: '#/components/parameters/DmEventExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2DmConversationsIdDmEventsResponse'
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:
- dm.read
- tweet.read
- users.read
- UserToken: []
tags:
- Direct Messages
summary: Get DM events
description: Retrieves a list of recent direct message events across all conversations.
operationId: getDirectMessagesEvents
parameters:
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationToken32'
style: form
- name: event_types
in: query
description: The set of event_types to include in the results.
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- MessageCreate
- ParticipantsJoin
- ParticipantsLeave
default:
- MessageCreate
- ParticipantsLeave
- ParticipantsJoin
example:
- MessageCreate
- ParticipantsLeave
explode: false
style: form
- $ref: '#/components/parameters/DmEventFieldsParameter'
- $ref: '#/components/parameters/DmEventExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2DmEventsResponse'
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.read
- dm.write
- 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
description: The ID of the direct-message event to delete.
required: true
schema:
$ref: '#/components/schemas/DmEventId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDmResponse'
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:
- dm.read
- tweet.read
- users.read
- UserToken: []
tags:
- Direct Messages
summary: Get DM event by ID
description: Retrieves details of a specific direct message event by its ID.
operationId: getDirectMessagesEventsById
parameters:
- name: event_id
in: path
description: dm event id.
required: true
schema:
$ref: '#/components/schemas/DmEventId'
style: simple
- $ref: '#/components/parameters/DmEventFieldsParameter'
- $ref: '#/components/parameters/DmEventExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2DmEventsEventIdResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
PollOption:
type: object
description: Describes a choice in a Poll object.
required:
- position
- label
- votes
properties:
label:
$ref: '#/components/schemas/PollOptionLabel'
position:
type: integer
description: Position of this choice in the poll.
votes:
type: integer
description: Number of users who voted for this choice.
Get2DmConversationsWithParticipantIdDmEventsResponse:
type: object
properties:
data:
type: array
minItems: 1
items:
$ref: '#/components/schemas/DmEvent'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
includes:
$ref: '#/components/schemas/Expansions'
meta:
type: object
properties:
next_token:
$ref: '#/components/schemas/NextToken'
previous_token:
$ref: '#/components/schemas/PreviousToken'
result_count:
$ref: '#/components/schemas/ResultCount'
PlaceId:
type: string
description: The identifier for this place.
example: f7eb2fa2fea288b1
Problem:
type: object
description: An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).
required:
- type
- title
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
discriminator:
propertyName: type
mapping:
about:blank: '#/components/schemas/GenericProblem'
https://api.twitter.com/2/problems/client-disconnected: '#/components/schemas/ClientDisconnectedProblem'
https://api.twitter.com/2/problems/client-forbidden: '#/components/schemas/ClientForbiddenProblem'
https://api.twitter.com/2/problems/conflict: '#/components/schemas/ConflictProblem'
https://api.twitter.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
https://api.twitter.com/2/problems/duplicate-rules: '#/components/schemas/DuplicateRuleProblem'
https://api.twitter.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
https://api.twitter.com/2/problems/invalid-rules: '#/components/schemas/InvalidRuleProblem'
https://api.twitter.com/2/problems/noncompliant-rules: '#/components/schemas/NonCompliantRulesProblem'
https://api.twitter.com/2/problems/not-authorized-for-field: '#/components/schemas/FieldUnauthorizedProblem'
https://api.twitter.com/2/problems/not-authorized-for-resource: '#/components/schemas/ResourceUnauthorizedProblem'
https://api.twitter.com/2/problems/operational-disconnect: '#/components/schemas/OperationalDisconnectProblem'
https://api.twitter.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
https://api.twitter.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
https://api.twitter.com/2/problems/rule-cap: '#/components/schemas/RulesCapProblem'
https://api.twitter.com/2/problems/streaming-connection: '#/components/schemas/ConnectionExceptionProblem'
https://api.twitter.com/2/problems/unsupported-authentication: '#/components/schemas/UnsupportedAuthenticationProblem'
https://api.twitter.com/2/problems/usage-capped: '#/components/schemas/UsageCapExceededProblem'
Get2DmEventsEventIdResponse:
type: object
properties:
data:
$ref: '#/components/schemas/DmEvent'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
includes:
$ref: '#/components/schemas/Expansions'
MediaId:
type: string
description: The unique identifier of this Media.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
PaginationToken32:
type: string
description: A base32 pagination token.
minLength: 16
UserId:
type: string
description: Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
pattern: ^[0-9]{1,19}$
example: '2244994945'
Position:
type: array
description: A [GeoJson Position](https://tools.ietf.org/html/rfc7946#section-3.1.1) in the format `[longitude,latitude]`.
minItems: 2
maxItems: 2
items:
type: number
example:
- -105.18816086351444
- 40.247749999999996
MentionEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/MentionFields'
UrlFields:
type: object
description: Represent the portion of text recognized as a URL.
required:
- url
properties:
description:
type: string
description: Description of the URL landing page.
example: This is a description of the website.
display_url:
type: string
description: The URL as displayed in the X client.
example: twittercommunity.com/t/introducing-…
expanded_url:
$ref: '#/components/schemas/Url'
images:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlImage'
media_key:
$ref: '#/components/schemas/MediaKey'
status:
$ref: '#/components/schemas/HttpStatusCode'
title:
type: string
description: Title of the page the URL points to.
example: Introducing the v2 follow lookup endpoints
unwound_url:
type: string
description: Fully resolved url.
format: uri
example: https://twittercommunity.com/t/introducing-the-v2-follow-lookup-endpoints/147118
url:
$ref: '#/components/schemas/Url'
Get2DmConversationsIdDmEventsResponse:
type: object
properties:
data:
type: array
minItems: 1
items:
$ref: '#/components/schemas/DmEvent'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
includes:
$ref: '#/components/schemas/Expansions'
meta:
type: object
properties:
next_token:
$ref: '#/components/schemas/NextToken'
previous_token:
$ref: '#/components/schemas/PreviousToken'
result_count:
$ref: '#/components/schemas/ResultCount'
Topic:
type: object
description: The topic of a Space, as selected by its creator.
required:
- id
- name
properties:
description:
type: string
description: The description of the given topic.
example: All about technology
id:
$ref: '#/components/schemas/TopicId'
name:
type: string
description: The name of the given topic.
example: Technology
Url:
type: string
description: A validly formatted URL.
format: uri
example: https://developer.twitter.com/en/docs/twitter-api
MediaKey:
type: string
description: The Media Key identifier for this attachment.
pattern: ^([0-9]+)_([0-9]+)$
EntityIndicesInclusiveInclusive:
type: object
description: Represent a boundary range (start and end index) for a recognized entity (for example a hashtag or a mention). `start` must be smaller than `end`. The start index is inclusive, the end index is inclusive.
required:
- start
- end
properties:
end:
type: integer
description: Index (zero-based) at which position this entity ends. The index is inclusive.
minimum: 0
example: 61
start:
type: integer
description: Index (zero-based) at which position this entity starts. The index is inclusive.
minimum: 0
example: 50
Tweet:
type: object
properties:
attachments:
type: object
description: Specifies the type of attachments (if any) present in this Tweet.
properties:
media_keys:
type: array
description: A list of Media Keys for each one of the media attachments (if media are attached).
minItems: 1
items:
$ref: '#/components/schemas/MediaKey'
media_source_tweet_id:
type: array
description: A list of Posts the media on this Tweet was originally posted in. For example, if the media on a tweet is re-used in another Tweet, this refers to the original, source Tweet..
minItems: 1
items:
$ref: '#/components/schemas/TweetId'
poll_ids:
type: array
description: A list of poll IDs (if polls are attached).
minItems: 1
items:
$ref: '#/components/schemas/PollId'
author_id:
$ref: '#/components/schemas/UserId'
community_id:
$ref: '#/components/schemas/CommunityId'
context_annotations:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ContextAnnotation'
conversation_id:
$ref: '#/components/schemas/TweetId'
created_at:
type: string
description: Creation time of the Tweet.
format: date-time
example: '2021-01-06T18:40:40.000Z'
display_text_range:
$ref: '#/components/schemas/DisplayTextRange'
edit_controls:
type: object
required:
- is_edit_eligible
- editable_until
- edits_remaining
properties:
editable_until:
type: string
description: Time when Tweet is no longer editable.
format: date-time
example: '2021-01-06T18:40:40.000Z'
edits_remaining:
type: integer
description: Number of times this Tweet can be edited.
is_edit_eligible:
type: boolean
description: Indicates if this Tweet is eligible to be edited.
example: false
edit_history_tweet_ids:
type: array
description: A list of Tweet Ids in this Tweet chain.
minItems: 1
items:
$ref: '#/components/schemas/TweetId'
entities:
$ref: '#/components/schemas/FullTextEntities'
geo:
type: object
description: The location tagged on the Tweet, if the user provided one.
properties:
coordinates:
$ref: '#/components/schemas/Point'
place_id:
$ref: '#/components/schemas/PlaceId'
id:
$ref: '#/components/schemas/TweetId'
in_reply_to_user_id:
$ref: '#/components/schemas/UserId'
lang:
type: string
description: Language of the Tweet, if detected by X. Returned as a BCP47 language tag.
example: en
matched_media_notes:
type: object
description: The matched media notes for the post.
properties:
match_status:
type: string
description: The status of the media note match.
example: matched_and_shown
note_id:
$ref: '#/components/schemas/NoteId'
non_public_metrics:
type: object
description: Nonpublic engagement metrics for the Tweet at the time of the request.
properties:
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
format: int32
note_request_suggestions:
type: object
description: The note request suggestions for the post.
properties:
source_link:
$ref: '#/components/schemas/UrlEntity'
suggestion:
type: string
description: The text of the note request suggestion.
suggestion_id:
type: string
description: The unique identifier of the note request suggestion.
note_tweet:
type: object
description: The full-content of the Tweet, including text beyond 280 characters.
properties:
entities:
type: object
properties:
cashtags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/CashtagEntity'
hashtags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/HashtagEntity'
mentions:
type: array
minItems: 1
items:
$ref: '#/components/schemas/MentionEntity'
urls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlEntity'
text:
$ref: '#/components/schemas/NoteTweetText'
organic_metrics:
type: object
description: Organic nonpublic engagement metrics for the Tweet at the time of the request.
required:
- impression_count
- retweet_count
- reply_count
- like_count
properties:
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
like_count:
type: integer
description: Number of times this Tweet has been liked.
reply_count:
type: integer
description: Number of times this Tweet has been replied to.
retweet_count:
type: integer
description: Number of times this Tweet has been Retweeted.
paid_partnership:
type: boolean
description: Indicates if this Post is a paid partnership, i.e. it has been disclosed by the author as containing paid promotion.
example: false
possibly_sensitive:
type: boolean
description: Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences.
example: false
promoted_metrics:
type: object
description: Promoted nonpublic engagement metrics for the Tweet at the time of the request.
properties:
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
format: int32
like_count:
type: integer
description: Number of times this Tweet has been liked.
format: int32
reply_count:
type: integer
description: Number of times this Tweet has been replied to.
format: int32
retweet_count:
type: integer
description: Number of times this Tweet has been Retweeted.
format: int32
public_metrics:
type: object
description: Engagement metrics for the Tweet at the time of the request.
required:
- retweet_count
- reply_count
- like_count
- impression_count
- bookmark_count
properties:
bookmark_count:
type: integer
description: Number of times this Tweet has been bookmarked.
format: int32
impression_count:
type: integer
description: Number of times this Tweet has been viewed.
format: int32
like_count:
type: integer
description: Number of times this Tweet has been liked.
quote_count:
type: integer
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter-x/refs/heads/main/openapi/twitter-x-direct-messages-api-openapi.yml