Twitter/X Articles API
Endpoints related to retrieving, creating & modifying Articles
OpenAPI Specification
openapi: 3.0.0
info:
description: X API v2 available endpoints
version: '2.166'
title: X API v2 Account Activity Articles 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: Articles
description: Endpoints related to retrieving, creating & modifying Articles
externalDocs:
description: Find out more
url: https://developer.x.com/en/docs/twitter-api/tweets/lookup
paths:
/2/articles/draft:
post:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Articles
summary: Create draft Article
description: Creates a new Article draft that can later be published.
operationId: articleCreateDraft
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleDraftCreateRequest'
required: true
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleDraftCreateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/articles/{article_id}/publish:
post:
security:
- OAuth2UserToken:
- tweet.write
- UserToken: []
tags:
- Articles
summary: Publish Article
description: Publishes a draft Article, making it publicly visible.
operationId: articlePublish
parameters:
- name: article_id
in: path
description: The ID of the draft article to publish.
required: true
schema:
type: string
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ArticlePublishResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
ArticleId:
type: string
description: The unique identifier of this Article.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
ArticleDraftCreateResponse:
type: object
properties:
data:
type: object
description: The newly created draft Article.
required:
- id
- title
properties:
id:
$ref: '#/components/schemas/ArticleId'
title:
type: string
description: The title of the draft Article.
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
ArticlePublishResponse:
type: object
properties:
data:
type: object
description: The published Article's seed post.
required:
- post_id
properties:
post_id:
type: string
description: The ID of the post created for the published Article.
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
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'
ArticleDraftCreateRequest:
type: object
required:
- title
- content_state
properties:
content_state:
type: object
description: DraftJS content state representing the article body.
required:
- blocks
- entities
properties:
blocks:
type: array
description: The text blocks that make up the article body.
items:
type: object
description: A DraftJS content block.
required:
- text
- type
properties:
data:
type: object
description: Block-level metadata for mentions, hashtags, cashtags, and URLs.
properties:
cashtags:
type: array
description: Cashtag spans in this block.
items:
type: object
required:
- from_index
- to_index
- text
properties:
from_index:
type: integer
description: Start index of the tagged span.
minimum: 0
text:
type: string
description: The tagged text.
to_index:
type: integer
description: End index of the tagged span.
minimum: 0
additionalProperties: false
hashtags:
type: array
description: Hashtag spans in this block.
items:
type: object
required:
- from_index
- to_index
- text
properties:
from_index:
type: integer
description: Start index of the tagged span.
minimum: 0
text:
type: string
description: The tagged text.
to_index:
type: integer
description: End index of the tagged span.
minimum: 0
additionalProperties: false
mentions:
type: array
description: Mention spans in this block.
items:
type: object
required:
- from_index
- to_index
- text
properties:
from_index:
type: integer
description: Start index of the tagged span.
minimum: 0
text:
type: string
description: The tagged text.
to_index:
type: integer
description: End index of the tagged span.
minimum: 0
additionalProperties: false
urls:
type: array
description: URL spans in this block.
items:
type: object
required:
- from_index
- to_index
- text
properties:
from_index:
type: integer
description: Start index of the tagged span.
minimum: 0
text:
type: string
description: The tagged text.
to_index:
type: integer
description: End index of the tagged span.
minimum: 0
additionalProperties: false
additionalProperties: false
entity_ranges:
type: array
description: References to entries in entities.
items:
type: object
required:
- key
- offset
- length
properties:
key:
type: integer
description: Index into the entities array.
minimum: 0
length:
type: integer
description: Length of the entity range.
minimum: 0
offset:
type: integer
description: Start offset in the text.
minimum: 0
additionalProperties: false
inline_style_ranges:
type: array
description: Inline formatting ranges.
items:
type: object
required:
- offset
- length
- style
properties:
length:
type: integer
description: Length of the styled range.
minimum: 0
offset:
type: integer
description: Start offset in the text.
minimum: 0
style:
type: string
description: The inline style.
enum:
- bold
- italic
- strikethrough
additionalProperties: false
key:
type: string
description: Optional block key.
text:
type: string
description: The text content of this block.
type:
type: string
description: The block type.
enum:
- unstyled
- header-one
- header-two
- header-three
- unordered-list-item
- ordered-list-item
- blockquote
- atomic
additionalProperties: false
entities:
type: array
description: Non-text entities referenced by blocks (links, embedded posts, images).
items:
type: object
required:
- key
- value
properties:
key:
type: string
description: The entity key referenced by entity_ranges.
value:
type: object
required:
- type
- mutability
- data
properties:
data:
type: object
description: Entity payload. Fields depend on the entity type.
properties:
caption:
type: string
description: Caption text.
entity_key:
type: string
description: Opaque entity key.
markdown:
type: string
description: Markdown content.
media_items:
type: array
description: Media keys. Used with type image.
items:
type: object
description: A reference to uploaded media, identified by category and ID.
required:
- media_category
- media_id
properties:
media_category:
type: string
description: The media category (e.g., TWEET_IMAGE).
media_id:
type: string
description: The media ID from the media upload endpoint.
additionalProperties: false
post_id:
type: string
description: The ID of the post to embed. Used with type post.
url:
type: string
description: The URL. Used with type link.
additionalProperties: false
mutability:
type: string
description: Whether the entity can be edited.
enum:
- immutable
- mutable
- segmented
type:
type: string
description: The entity type.
enum:
- post
- link
- image
additionalProperties: false
additionalProperties: false
additionalProperties: false
cover_media:
type: object
description: A reference to uploaded media, identified by category and ID.
required:
- media_category
- media_id
properties:
media_category:
type: string
description: The media category (e.g., TWEET_IMAGE).
media_id:
type: string
description: The media ID from the media upload endpoint.
additionalProperties: false
title:
type: string
description: The title of the article.
minLength: 1
additionalProperties: false
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
securitySchemes:
BearerToken:
type: http
scheme: bearer
OAuth2UserToken:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://api.x.com/2/oauth2/authorize
tokenUrl: https://api.x.com/2/oauth2/token
scopes:
block.read: View accounts you have blocked.
bookmark.read: Read your bookmarked Posts.
bookmark.write: Create and delete your bookmarks.
dm.read: Read all your Direct Messages.
dm.write: Send and manage your Direct Messages.
follows.read: View accounts you follow and accounts following you.
follows.write: Follow and unfollow accounts on your behalf.
like.read: View Posts you have liked and likes you can see.
like.write: Like and unlike Posts on your behalf.
list.read: View Lists, members, and followers of Lists you created or are a member of, including private Lists.
list.write: Create and manage Lists on your behalf.
media.write: Upload media, such as photos and videos, on your behalf.
mute.read: View accounts you have muted.
mute.write: Mute and unmute accounts on your behalf.
offline.access: Request a refresh token for the app.
space.read: View all Spaces you have access to.
timeline.read: View all Custom Timelines you can see, including public Custom Timelines from other developers.
tweet.moderate.write: Hide and unhide replies to your Posts.
tweet.read: View all Posts you can see, including those from protected accounts.
tweet.write: Post and repost on your behalf.
users.read: View any account you can see, including protected accounts.
UserToken:
type: http
scheme: OAuth