|
| 1 | +--- |
| 2 | +title: Introduction |
| 3 | +description: "Use the X API Articles endpoints to programmatically create draft long-form Articles with rich text, media, and embeds, then publish them to X." |
| 4 | +sidebarTitle: Introduction |
| 5 | +keywords: ["articles", "articles API", "long-form", "long-form posts", "create article", "draft article", "publish article", "write articles"] |
| 6 | +--- |
| 7 | + |
| 8 | +The Articles endpoints allow developers to create draft Articles and publish them on X programmatically. Articles are long-form posts that support rich text formatting, embedded posts, links, and images. |
| 9 | + |
| 10 | +These endpoints require user-auth authentication via OAuth 1.0a or OAuth 2.0 PKCE with the `tweet.read`, `tweet.write`, and `users.read` scopes. |
| 11 | + |
| 12 | +Currently, the API supports two endpoints: |
| 13 | + |
| 14 | +## Create a draft Article |
| 15 | + |
| 16 | +Developers can create a new draft Article using the `POST https://api.x.com/2/articles/draft` endpoint. The request body contains the article title, the body content as a [DraftJS](https://draftjs.org/docs/api-reference-content-state) content state of text blocks and entities, and optional cover media uploaded via the [media upload endpoints](/x-api/media/introduction). |
| 17 | + |
| 18 | +## Publish an Article |
| 19 | + |
| 20 | +Once a draft is ready, developers can make it publicly visible using the `POST https://api.x.com/2/articles/{article_id}/publish` endpoint, where `article_id` is the ID returned when the draft was created. |
| 21 | + |
| 22 | +## Getting started |
| 23 | + |
| 24 | +To use the endpoints, you need a user access token. For details on generating one, see the [OAuth 2.0 Authorization Code Flow with PKCE](/fundamentals/authentication/oauth-2-0/authorization-code) documentation. |
| 25 | + |
| 26 | +Once you have the access token, you can create a draft Article as shown below: |
| 27 | + |
| 28 | +```bash |
| 29 | +curl --request POST 'https://api.x.com/2/articles/draft' \ |
| 30 | + --header 'Authorization: Bearer XXXXX' \ |
| 31 | + --header 'Content-Type: application/json' \ |
| 32 | + --data '{ |
| 33 | + "title": "My first Article", |
| 34 | + "content_state": { |
| 35 | + "blocks": [ |
| 36 | + { |
| 37 | + "text": "Hello from the Articles API!", |
| 38 | + "type": "unstyled" |
| 39 | + } |
| 40 | + ], |
| 41 | + "entities": [] |
| 42 | + } |
| 43 | + }' |
| 44 | +``` |
| 45 | + |
| 46 | +If the request is successful, you should see the JSON response as shown below: |
| 47 | + |
| 48 | +```json |
| 49 | +{ |
| 50 | + "data": { |
| 51 | + "id": "1146654567674912769", |
| 52 | + "title": "My first Article" |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +You can then publish the draft using the returned Article ID: |
| 58 | + |
| 59 | +```bash |
| 60 | +curl --request POST 'https://api.x.com/2/articles/1146654567674912769/publish' \ |
| 61 | + --header 'Authorization: Bearer XXXXX' |
| 62 | +``` |
| 63 | + |
| 64 | +If the request is successful, the response contains the ID of the post created for the published Article: |
| 65 | + |
| 66 | +```json |
| 67 | +{ |
| 68 | + "data": { |
| 69 | + "post_id": "1346889436626259968" |
| 70 | + } |
| 71 | +} |
| 72 | +``` |
0 commit comments