Create Tweet API

POST tweet/create posts a new tweet from the account behind your registered twitterapis session. It accepts plain text, up to 4 image media_ids, a reply_to tweet ID, or a quote tweet ID in a single call. The response returns ok (boolean), the created tweet_id, and its canonical x.com url. Each call costs $0.0016.

curl -X POST "https://example.com/tweet/create" \  -H "Content-Type: application/json" \  -d '{    "text": "Shipping cursor-paginated bookmarks today."  }'

{  "ok": true,  "tweet_id": "1759123456789012345",  "url": "https://x.com/i/status/1759123456789012345"}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "forbidden",  "message": "The acting account is not authorized for this write action, or has no logged-in session."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use tweet/create to publish a brand-new tweet from your registered account, whether it's a standalone text post, a reply to an existing tweet, a quote tweet, or a post with up to 4 attached images. Reach for a sibling Write Action instead when the operation isn't originating a new tweet: use media/upload first to get media_ids, or a delete/retweet/favorite endpoint for actions on tweets that already exist.

Notes

• [VERIFY] Success body sourced from backend routes/tweet-write.ts (shape: { ok: true, tweet_id, url }); not executed live.
• Needs a session for the account you are reading: either register one once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers, which let a single API key act as many accounts. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.
• Upload media via media/upload first to get media_ids; up to 4 images per tweet.

Related endpoints

• Upload Media: Upload an image and get a media_id to attach to a tweet.
• Media Status: Check the async processing state of an uploaded media_id.

FAQ

How do I attach images to a tweet created with this endpoint?

Upload each image first with media/upload to get a media ID, then pass up to 4 of those IDs in the media_ids parameter of tweet/create. media_ids is optional and takes no images if omitted.

What does tweet/create return if the post fails?

The response always includes ok as a boolean. When ok is false, tweet_id and url are null instead of populated values, so check ok before reading either field rather than assuming a non-null response.

Can I use tweet/create to both reply to and quote a tweet in the same call?

The endpoint exposes reply_to and quote as two separate optional string parameters, each taking an existing tweet ID, and both can be supplied on the same request since neither is documented as mutually exclusive with the other.