Articles

Publish an X Article: built in a draft, read back, and published only if X kept every block.

Early access. Tell us what you're building and we'll set you up. Contact us

An Article takes minutes to build, longer than a request may wait, so POST /articles starts it and answers 202, and GET /articles/{key} says where it is. The browser builds it in a new X draft (title, every block in order, cover), reads the saved draft back, and publishes it only if X kept exactly those blocks. Otherwise nothing is published and the draft stays in the account's Drafts.

Publish One#

POST /articles (accounts.write, Idempotency-Key required, JSON):

JSON

{
  "account_id": "janedemo",
  "title": "How we ship every week",
  "cover": { "name": "cover.png", "content_type": "image/png", "data_base64": "…" },
  "blocks": [
    { "kind": "text", "html": "<p>Every Monday we pick one thing…</p>", "plain": "Every Monday we pick one thing…" },
    { "kind": "image", "alt": "Our board", "file": { "name": "board.png", "content_type": "image/png", "data_base64": "…" } },
    { "kind": "code", "text": "git tag v1.4.0" }
  ],
  "dry_run": false
}

title up to 200 characters; 1–200 blocks.
text blocks are pasted as HTML: headings, bold, italics, lists and links survive.
Images are JPEG, PNG or WebP, 8 MB each, 30 at most, 40 MB in all. cover is optional (5:2 works best).
dry_run: true builds and checks the draft but never publishes, and doesn't count toward the pace. Articles otherwise share the posts' pace.

JSON

{ "object": "ArticleJob", "id": "article-2026-11-07", "account_id": "11111111-1111-4111-8111-111111111111", "status": "building", "detail": "Starting." }

Follow One#

GET /articles/{idempotency_key} (accounts.read):

`status`	HTTP	Meaning
`building`	202	Still being built. Ask again in a minute.
`published`	200	Live, with `url` and `article_id`. Final.
`draft`	200	Dry run: built and checked, `draft_url`, nothing published. Final.
`not_sent`	422 (409 for `account_busy`)	Nothing was published; `code` and `detail` say why. Safe to retry with the same key.
`unknown`	200	Publish was pressed but X didn't confirm. Check the account's Articles before sending again.

The same key never builds twice. One Article builds per account at a time; other X calls on that account answer 409 errors/account_busy until it ends.

Was this page helpful?