Need help with your APIs? I offer API discovery, governance & evangelism services. Explore services →
API Evangelist API Evangelist
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC

X (Twitter) Media API

Endpoints related to Media

X (Twitter) Media API is one of 23 APIs that X (Twitter) publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include Media. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, a getting-started guide, an API reference, authentication docs, and rate-limit docs.

This API exposes 11 operations across 9 paths, and defines 47 schemas. It is described by OpenAPI 3.0.0, at version 2.161.

Requests are made against a single base URL, https://api.x.com.

11 operations 9 paths 47 schemas 1 DELETE4 GET6 POST

Metadata

The identity and technical contract details declared by the specification.

Specification
OpenAPI 3.0.0
API Version
2.161
Base URL
https://api.x.com/2
Authentication
HTTP Bearer, OAuth 2.0, HTTP Oauth
Terms of Service
Resource Areas
1

Authentication & Security 3

X (Twitter) Media API declares 3 security schemes for authenticating requests. It accepts HTTP bearer tokens (BearerToken). It supports OAuth 2.0 (OAuth2UserToken) using the authorizationCode flow, exposing 21 scopes. It uses HTTP oauth authentication (UserToken).

Paths & Operations 11

Across 9 paths, the API surfaces 11 operations — 1 DELETE, 4 GET, 6 POST. Each is listed below with its method, path, parameters, and response codes.

Media 11

Endpoints related to Media

GET
/2/media
X Get Media by Media Keys
getMediaByMediaKeys 2 params → 200default
GET
/2/media/analytics
X Get Media Analytics
getMediaAnalytics 5 params → 200default
POST
/2/media/metadata
X Create Media Metadata
createMediaMetadata body → 200default
DELETE
/2/media/subtitles
X Delete Media Subtitles
deleteMediaSubtitles body → 200default
POST
/2/media/subtitles
X Create Media Subtitles
createMediaSubtitles body → 200default
GET
/2/media/upload
X Get Media Upload Status
getMediaUploadStatus 2 params → 200default
POST
/2/media/upload
X Upload Media
mediaUpload body → 200default
POST
/2/media/upload/initialize
X Initialize Media Upload
initializeMediaUpload body → 200default
POST
/2/media/upload/{id}/append
X Append Media Upload
appendMediaUpload 1 param body → 200default
POST
/2/media/upload/{id}/finalize
X Finalize Media Upload
finalizeMediaUpload 1 param → 200default
GET
/2/media/{media_key}
X Get Media by Media Key
getMediaByMediaKey 2 params → 200default

Schemas 47

The contract defines 47 schemas that model the data the API accepts and returns. The most detailed are MediaMetrics (10 properties), Sticker (10 properties), MediaUploadConfigRequest (5 properties), MediaUploadRequestOneShot (5 properties). Each schema is shown below with its type and property counts.

SubtitlesCreateRequest
object
3 properties
MediaMetrics
object
10 properties
Media
object
4 properties 1 required
MediaAnalytics
object
2 properties
MediaSegments
ProcessingInfo
object
3 properties 1 required
Get2MediaResponse
object
2 properties
StickerInfo
object
1 property 1 required
ContentExpiration
object
1 property 1 required
AudiencePolicy
object
2 properties
MediaUploadAppendResponse
object
A response from getting a media upload request status.
2 properties 1 required
MediaUploadRequestOneShot
object
5 properties 2 required
MediaId
string
The unique identifier of this Media.
Get2MediaMediaKeyResponse
object
2 properties
SensitiveMediaWarning
object
3 properties
MetadataCreateRequest
object
2 properties 1 required
MediaTimestampedMetrics
object
2 properties
SubtitleLanguageCode
string
The language code should be a BCP47 code (e.g. 'EN", "SP")
MediaPayloadBinary
string
The file to upload.
Subtitles
object
3 properties
AllowDownloadStatus
object
1 property
PreviewImage
object
1 property 1 required
MediaKey
string
The Media Key identifier for this attachment.
SubtitlesCreateResponse
object
2 properties
MediaUploadResponse
object
A response from getting a media upload request status.
2 properties 1 required
Sticker
object
10 properties
Error
object
2 properties 2 required
AltText
object
1 property 1 required
MediaCategorySubtitles
string
The media category of uploaded media to which subtitles should be added/deleted
DomainRestrictions
object
1 property 1 required
MediaHeight
integer
The height of the media in pixels.
FoundMediaOrigin
object
2 properties 2 required
MediaCategoryOneShot
string
A string enum value which identifies a media use-case. This identifier is used to enforce use-case specific constraints (e.g. file size) and enable advanced fe…
UploadSource
object
1 property 1 required
MetadataCreateResponse
object
2 properties
SubtitlesDeleteRequest
object
3 properties
MediaUploadAppendRequest
SubtitlesDeleteResponse
object
2 properties
Problem
object
An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).
4 properties 2 required
MediaCategory
string
A string enum value which identifies a media use-case. This identifier is used to enforce use-case specific constraints (e.g. file size, video duration) and en…
SharedInfo
object
1 property 1 required
GeoRestrictions
MediaUploadConfigRequest
object
5 properties
ManagementInfo
object
1 property 1 required
MediaPayloadByte
string
The file to upload.
MediaWidth
integer
The width of the media in pixels.
UserId
string
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.

Specification

The full machine-readable OpenAPI contract behind this narrative.

Source

twitter-media-api-openapi.yml Raw ↑

Other APIs X (Twitter) publishes across the network.

X Ads API
X Activity API
X (Twitter) Account Activity API
X (Twitter) Activity API
X (Twitter) Bookmarks API
X (Twitter) Chat API
X (Twitter) Communities API
X (Twitter) Community Notes API
X (Twitter) Compliance API
X (Twitter) Connections API
X (Twitter) Direct Messages API
X (Twitter) General API