How to Publish X Articles via API
(content_state Explained)

Before You Write Any Code

curl -X POST https://opentweet.io/api/v1/articles \
  -H "Authorization: Bearer ot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Why We Ship Weekly",
    "content_markdown": "# Why we ship weekly\n\nShipping **every week** keeps the feedback loop short.\n\n![Our release dashboard](https://example.com/dashboard.png)",
    "scheduled_date": "2026-07-15T14:00:00Z"
  }'

The response is the stored article, ready to publish at the scheduled time:

{
  "article": {
    "id": "686d2f9ab1c4e8d92f1a7c03",
    "title": "Why We Ship Weekly",
    "content_markdown": "# Why we ship weekly\n\nShipping **every week**...",
    "cover_image_url": null,
    "status": "scheduled",
    "scheduled_date": "2026-07-15T14:00:00.000Z",
    "published_date": null,
    "x_article_id": null,
    "x_post_id": null,
    "article_url": null,
    "failed_reason": null,
    "x_account_id": null,
    "created_at": "2026-07-09T10:12:44.000Z",
    "updated_at": "2026-07-09T10:12:44.000Z"
  }
}

To skip scheduling, pass publish_now: true (mutually exclusive with scheduled_date), or publish any stored article by ID:

# Publish immediately instead of scheduling
curl -X POST https://opentweet.io/api/v1/articles \
  -H "Authorization: Bearer ot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Why We Ship Weekly",
    "content_markdown": "# Why we ship weekly\n\n...",
    "publish_now": true
  }'

# Or publish an existing draft or scheduled article by ID
curl -X POST https://opentweet.io/api/v1/articles/686d2f9ab1c4e8d92f1a7c03/publish \
  -H "Authorization: Bearer ot_your_api_key"
# => article.status becomes "published" and article_url
#    points at the live post on X

All Article Endpoints

Article status moves through draft, scheduled, publishing, published, and failed. A failed publish returns X's exact error as failed_reason (Premium missing on the account is the most common one), and a PUT on a failed article resets it so you can try again. Multi-account users can target a specific account with x_account_id. Full reference in the API docs.

What the One Call Does for You

• Markdown to content_state conversion: headings, bold, italic, strikethrough, links, lists, and quotes map to the right block types and inline_style_ranges
• Image handling: every  in your markdown is uploaded to X as tweet_image and wired into an atomic block; failed uploads fall back to plain links instead of dropping content
• Embedded posts: an x.com status URL on its own line becomes an embedded post entity
• Mention, hashtag, and cashtag spans in block data so they render as live links
• The draft-then-publish flow, OAuth token refresh, and cover image upload
• Scheduling: pass scheduled_date and a scheduler publishes at that time; failures are stored with X's exact error as failed_reason so you can fix and re-publish

One honest limit carries over from X: since content_state has no code-block type, fenced code in your markdown is preserved as plain text, not formatted code. Articles require a paid OpenTweet plan (not available during the trial). See pricing.

Tips for Programmatic Articles