Write Actions - twexapi

Read-only routes need a TwexAPI API key. Write routes also need a Twitter cookie or auth_token on the request so TwexAPI can act as the logged-in account. Use this page for posting, replies, likes, retweets, bookmarks, follows, and DMs. Preview payloads with the CLI --dry-run before sending from agents or production jobs.

What counts as a write

Action	Route	Required fields
Post or reply	`POST /twitter/tweets/create`	`tweet_content`, `cookie`
Like	`POST /twitter/tweets/{tweet_id}/like`	`cookie`
Follow	`POST /twitter/user/follow`	`username`, `cookie`
Send DM	`POST /twitter/send-dm`	`username`, `msg`, `cookie`

Related writes use the same cookie rule: retweet, bookmark, unfollow, unlike, thread create, and XChat DM. MCP marks these endpoints read_only: false. Require human approval before any agent calls them. See Create a Tweet or Reply.

Never put cookies, auth_token values, or API keys in agent chat, handoff JSON, logs that leave your vault, or public repositories.

Credentials you need

TwexAPI API key

Create a key in the dashboard. Send it as Authorization: Bearer YOUR_API_KEY (REST/SDK) or x-api-key (MCP).

Twitter session

Supply a cookie string or an auth_token. Most write bodies accept either in the cookie field.

Optional cookie lookup

If you only have auth_token, convert it with Get cookie by auth token (GET /twitter/{auth_token}/cookie), then store the returned cookie as a secret.

Value	Typical contents	Use
Cookie string	Includes `auth_token` and `ct0` (and other session cookies)	Preferred for writes. Pass the whole header-style string in `cookie`.
`auth_token` only	Single token from the same session	Accepted on write `cookie` fields. Convert to a full cookie when an endpoint rejects a token-only value.

Export the session from a browser that is already logged into X/Twitter. Copy at least auth_token and ct0. Treat the export as a password: it can post, follow, and DM as that account.

Store secrets

export X_API_SCRAPER_KEY="YOUR_API_KEY"
export TWITTER_COOKIE="auth_token=...; ct0=..."

CLI named profiles keep the same values off the command line:

x-api-scraper auth apps add --name prod --api-key "YOUR_API_KEY"
x-api-scraper auth profiles add --name founder --cookie "$TWITTER_COOKIE"
x-api-scraper auth apps use prod
x-api-scraper auth profiles use founder

Default CLI config is plain JSON in ~/.x-api-scraper/config.json. Restrict file permissions and do not commit that directory. SDK pattern (Python):

tweet = client.tweets.actions.create(
    tweet_content="Hello from TwexAPI.",
    cookie=os.getenv("TWITTER_COOKIE"),
)

REST pattern:

curl --request POST \
  --url 'https://api.twexapi.io/twitter/tweets/create' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "tweet_content": "Hello from TwexAPI.",
    "cookie": "auth_token=...; ct0=..."
  }'

MCP agents still send the API key on the MCP connection. Pass cookie only inside the twexapi_request body after a human approves the exact text, target, and media URLs.

Preview before you send

x-api-scraper --app prod --profile founder --dry-run tweet create --text "hello from cli"

Dry-run validates the payload without creating the tweet. Use it from n8n, Zapier, and agent pipelines before the live call. Local file upload is not supported. Attach public --media-url values (up to 4 images, or 1 GIF, or 1 MP4 up to 100 MB).

Did the write succeed?

TwexAPI does not expose a separate write-action polling API. HTTP 200 with a tweet ID, message ID, or success envelope is the primary confirmation. Timeouts and 5xx are ambiguous: the write might have landed.

Persist an audit row

Store these fields before retrying:

Field	Why
`method` and `path`	Identifies the action
Request fingerprint	Hash of text, target ID/username, and media URLs
Returned `tweet_id` / `messageId`	Proof the side effect exists
HTTP status and body	Distinguishes credit errors from cookie errors
Approval record	Who confirmed a `read_only: false` MCP call

Check with a read before duplicating

If you tried to…	Confirm with…	Retry only if…
Post a tweet	User timeline or tweet lookup for the same text and timestamp window	No matching `tweet_id`
Reply	Thread/replies for `reply_tweet_id`	Your reply ID is missing
Like	Tweet detail / favorited state	The tweet is not liked
Follow	Following relationship for `username`	The account is not followed
Send DM	DM history / status for that user	The `messageId` is missing

Do not fire the same write again because the client timed out. Look up first, then retry once with the same fingerprint.

Credits and `403`

Metered writes spend account credits. 403 often means no available credits or the action is not allowed for the key/account.

Stop write traffic

Pause agents, n8n batches, and CLI loops. Retrying a failed post can create duplicates after credits return.

Check balance

Call Get Balance:

curl --request GET \
  --url 'https://api.twexapi.io/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Top up, then resume once

Restore credits in the dashboard. Re-run only writes that failed the read-back check.

Status	Likely cause	Action
`401`	Bad API key	Replace `X_API_SCRAPER_KEY`
`403`	Credits exhausted or action blocked	Check balance; do not duplicate writes
`401`/`403` with cookie errors	Expired session	Export a fresh cookie / `auth_token`
`429`	Rate limit	Back off — see Rate Limits
`5xx` or timeout	Ambiguous	Read-back, then retry at most once

Full HTTP recovery: Error Handling.

Agent rules

Call MCP explore with include_writes: true only when the user asked for a write.
Stop before read_only: false. Show path, body preview, and target IDs.
After approval, send cookie from a secret store, not from the model.
Keep cookies out of the handoff JSON. Store tweet_id, route_used, and approval metadata only.

See Agent MCP Handoff and MCP Tools.

​What counts as a write

​Credentials you need

​Cookie vs auth_token

​Store secrets

​Preview before you send

​Did the write succeed?

​Persist an audit row

​Check with a read before duplicating

​Credits and 403

​Agent rules

​Related pages

What counts as a write

Credentials you need

Cookie vs `auth_token`

Store secrets

Preview before you send

Did the write succeed?

Persist an audit row

Check with a read before duplicating

Credits and `403`

Agent rules

Related pages