X write
Twitter post API for tweet & reply automation
Post tweets and replies from a connected X account with public image URLs or 1 MP4 video URL, write-status polling, and audit handoff. See action fields.
- 200
- 202
- 400
- 401
- 402
- 403
- 409
- 422
- 429
- 500
- 503
POST
Twitter post API for tweet & reply automation
30 credits text-only · attached media adds 2 credits per started MB across all files
media.
When POST /x/media hosts a local file, use its mediaUrl.
Never send mediaId or media_ids to this endpoint.
Send a unique Idempotency-Key.
Store the durable action.
Poll statusUrl while terminal is false.
X’s Create Post guide covers its separate endpoint.
Use Xquik authentication. Store its durable write fields.
Choose the Twitter post request
Choose among 6 tweet request formats. Include only the fields required below.
Create one
Idempotency-Key for each automatic Twitter posting request.
Reuse that key only when replaying the same network request. A new
tweet, reply, caption, media URL, account, or community requires a new key.
This endpoint starts the write immediately. It does not schedule future
delivery. Let your scheduler call it at the approved time. One request
publishes 1 tweet on X. Create replies with reply_to_tweet_id. Create each
thread tweet with a separate approved request.
Store the tweet write receipt
Persist the write receipt before another worker posts. Keep these field groups:- Store
idandrequest.hashfor request matching. - Store
accountandtargetfor the selected account and destination. - Store
status,terminal, andstatusUrlfor polling. - Store
safeToRetryfor retry decisions. - Store
result.result?.idortweetIdfor the published Tweet ID. - Store
billing.chargedCreditsfor billing checks.
Post with public media URLs
Usemedia for an image or MP4 at a public HTTPS URL.
For local files, call Upload Media first.
Pass its returned mediaUrl in media.
Send up to 4 image URLs or exactly 1 MP4 URL.
Keep the MP4 at 100 MB or less.
Never send media_ids; that field is for DMs only.
Attached media adds 2 credits per started MB across all files.
id, request.hash, billing, result, reply_to_tweet_id, and media. Poll Get Write Action Status while terminal is false. Retry only when safeToRetry is true, using a new key.
Headers
string
Send your Xquik API key in this header. Alternatively, send an OAuth 2.1 bearer token.
string
required
Unique key for this intended write. Reuse it only for an exact network replay.
string
required
Must be
application/json.Body
string
required
Choose the connected X account by username or account ID. Xquik removes an optional
@ prefix.string
Send up to 280 characters for a standard tweet. Note tweets accept up to 25,000 characters. Omit text only when
media exists.string
Set the parent Tweet ID. Xquik posts the new tweet inside that thread.
string
Set the target X Community ID. Confirm that the connected account is a member.
boolean
Set
true for a note tweet with up to 25,000 characters. The default is false.string[]
Attach public media URLs directly.
- Send up to 4 JPEG, PNG, GIF, WebP, or AVIF image URLs.
- Send exactly 1 public MP4 URL up to 100 MB.
- Never mix video with other media.
- Use Upload Media to host a local file.
- Pass its returned
mediaUrlinmedia. - Never pass uploaded
mediaIdvalues ormedia_ids. - Attached media adds 2 credits per started MB across all files.
Response
Durable write recovery
- Store
id, the nestedhashinrequest,billing, andstatusUrl. - Poll after
Retry-AfterorpollAfterMswhenterminalisfalse. - Trust
safeToRetryandnextActionbefore any new write.
200 Terminal or 202 active
Store terminal results. Poll active actions without creating another write.- After HTTP
200, store the result and settled billing. - After HTTP
202, poll the same action. Never submit another write. - After HTTP
400, fix the named field. Use a new idempotency key. - After HTTP
401, fix authentication. Do not retry unchanged. - After HTTP
402, fund the account before another write. - After HTTP
403, reconnect the account. - After HTTP
409, keep the original action. Use a new key for new input. - After HTTP
422, fix the rejected request before retrying. - After HTTP
429, wait forRetry-After. Preserve the same key. - After HTTP
500, retry only whensafeToRetryistrue. - After HTTP
503, poll whileterminalisfalse.
- 200
- 202
- 400
- 401
- 402
- 403
- 409
- 422
- 429
- 500
- 503
Twitter post API for tweet & reply automation