Developer docs
Build on XAutomator
Everything you can do in the dashboard, from your agent, your terminal or your own code. Every call goes through the same Safety Governor and costs the same credits as the app, so automation stays paced, approved and logged.
Let Claude, Cursor or any MCP agent run your X account with 28 tools.
xa in your terminal, plus a live keyboard dashboard.
JSON over HTTPS with API keys and signed webhooks.
Quickstart
- Create an API key in Developers, API keys. Keys start with
xa_live_. They are shown once, so store yours in a password manager. - Pick how you want to work: give the agent install prompt to your AI agent, install the CLI, or call the REST API.
- Check the cost first.
POST /estimate,xa estimateand thexa_estimate_costtool are free.
curl https://xautomator.com/api/v1/me \
-H "Authorization: Bearer $XAUTOMATOR_API_KEY"Authentication
Send your key as a bearer token on every request. Keys belong to your workspace and can do anything you can do in the app, so keep them out of client side code and repositories. Revoke a key in Developers at any time; it stops working immediately.
Authorization: Bearer xa_live_...MCP server
The XAutomator MCP server gives any MCP client 28 tools, 2 resources and 3 prompts: schedule posts and threads, work approvals, run Profile Studio rotations and Boost rules, and read credits, audit and analytics. Without a key it runs on built in mock data, so you can try every tool safely.
claude mcp add xautomator --scope user -e XAUTOMATOR_API_KEY=xa_live_... -- npx -y @xautomator/mcp{
"mcpServers": {
"xautomator": {
"command": "npx",
"args": [
"-y",
"@xautomator/mcp"
],
"env": {
"XAUTOMATOR_API_KEY": "xa_live_..."
}
}
}
}xa_whoamiWho is signed in, and whether the server runs on mock dataxa_list_accounts / xa_get_accountConnected accounts, health, approval modexa_pause_account / xa_resume_accountKill switch for one accountxa_update_safetyApproval mode, quiet hours and daily capsxa_estimate_costCredit cost before posting, plus the balancexa_create_postSchedule a post, thread or poll, or save a draftxa_list_posts / xa_get_post / xa_update_postRead and edit the queuexa_cancel_post / xa_send_post_nowCancel or send now (needs confirm)xa_list_approvals / xa_approve / xa_rejectWork the approval queuexa_list_rotations / xa_create_rotation / xa_update_rotation / xa_delete_rotationProfile Studioxa_list_boost_rules / xa_create_boost_ruleAuto plug and auto repostxa_get_balance / xa_get_ledgerCreditsxa_get_audit / xa_get_analytics / xa_list_alertsWhat happened and how it is goingxa_create_webhookSend events to your own endpointPrompts: plan_week_of_posts, setup_bio_rotation, weekly_report. Resources: xautomator://accounts, xautomator://credits. Tools that send, approve, resume or delete require confirm: true, so your agent has to ask you first.
Agent install prompt
Paste this into Claude Code, Claude Desktop, Cursor or any agent with a shell. It installs the server, connects it to your account and checks that it works.
Install and connect the XAutomator MCP server so you can manage my X automation for me.
1. Check that Node.js 22 or newer is installed (node --version). If it is missing or older, tell me and stop.
2. Ask me for my XAutomator API key. It starts with xa_live_ and I create it at https://xautomator.com/app/developers. Never print it back, log it or write it into any file in a repository.
3. Connect the server:
- Claude Code: run claude mcp add xautomator --scope user -e XAUTOMATOR_API_KEY=<key> -- npx -y @xautomator/mcp
- Claude Desktop, Cursor, Windsurf or another MCP client: add this to the client's MCP config (mcpServers), then restart the client:
{ "xautomator": { "command": "npx", "args": ["-y", "@xautomator/mcp"], "env": { "XAUTOMATOR_API_KEY": "<key>" } } }
4. Verify: call the xa_whoami tool and tell me who is signed in and on which plan. If it says mock data, the key was not picked up, so fix the config.
5. From now on, use the xa_ tools for anything about my X account. Always call xa_estimate_cost before creating posts, and ask me before you send anything immediately, approve an action, resume an account or delete something.
Docs: https://xautomator.com/docsCLI and TUI
The xa command does everything from your terminal. Run it with no arguments for a live dashboard you drive with the keyboard: tabs for Home, Queue, Approvals, Rotations, Credits and Audit, plus n to write a post, a to approve and p to pause.
npm install -g xautomator
xa loginxaOpen the terminal dashboardxa loginSave your API key (stored with read access for you only)xa accountsList connected X accountsxa post "Launch day" --thread "Here is why" --at 2026-11-25T09:30:00ZSchedule a threadxa estimate "New drop https://..."Credit cost before postingxa queue --status waitingThe queue, filteredxa approvals / xa approve <id>Work the approval queuexa pause <account>Kill switchxa credits --ledgerEvery credit in and outxa audit --limit 20Recent actionsxa mcpPrint MCP setup for your agentAdd --json to any command for machine readable output, and -y to skip confirmations in scripts.
REST API
Base URL https://xautomator.com/api/v1. Requests and responses are JSON. Lists come back as { "data": [...] }.
/meThe signed in user, plan and number of accounts./accountsEvery connected X account with health, paused state and approval mode./accounts/{id}One account's full settings./accounts/{id}Update approval_mode, quiet_hours or daily_caps./accounts/{id}/pauseKill switch. Pauses every scheduled and automated action./accounts/{id}/resumeResume a paused account./estimateCredit cost of a post or thread. Free./postsSchedule a post, thread or poll. Omit schedule_at to use the next free time slot./postsThe queue. Filter with status and account_id./posts/{id}One post with its status and the reason it is waiting or blocked./posts/{id}Edit the text, thread or time of an unsent post./posts/{id}Cancel a post. Costs nothing./posts/{id}/sendSend a queued post now. Passes the Safety Governor and costs credits./approvalsActions waiting for approval, with the reason and expiry./approvals/{id}/approveApprove and send. Pass always_allow_rule to trust the rule from now on./approvals/{id}/rejectReject. Nothing is sent and no credits are used./rotationsBio, name, location, website, avatar, banner and pinned post rotations./rotationsCreate a rotation. First run waits for approval./rotations/{id}Pause, resume or edit a rotation./rotations/{id}Delete a rotation./boost-rulesAuto plug, auto repost and auto delete rules./boost-rulesCreate a rule. Runs once per post./creditsPlan and pack balance./credits/ledgerEvery credit in and out./auditRecent actions with status, credits and trace./analyticsFollowers, growth, posts, average likes and credits spent for ?days=./alertsApprovals waiting, failures, low credits and health warnings./webhooksYour webhook endpoints./webhooksAdd an endpoint. Returns the signing secret once./webhooks/{id}Remove an endpoint.curl -X POST https://xautomator.com/api/v1/posts \
-H "Authorization: Bearer $XAUTOMATOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "acc_1",
"text": "Launch day. Here is everything that is new.",
"thread": ["Bio rotations now support {next_drop}.", "Try it: https://xautomator.com"],
"schedule_at": "2026-11-25T09:30:00Z"
}'{
"id": "post_k2x9",
"account_id": "acc_1",
"status": "queued",
"scheduled_at": "2026-11-25T09:30:00Z",
"credits": 9,
"reason": null
}Webhooks
Add an endpoint in Developers or with POST /webhooks. Each delivery is a JSON POST with an XAutomator-Signature header: an HMAC SHA 256 of the raw body using your endpoint's signing secret. Return any 2xx within 10 seconds; failed deliveries are retried with backoff for 24 hours.
post.sentA post, thread or profile change went out.post.failedX rejected an action. Its credits were refunded.approval.pendingAn action is waiting for approval.credits.lowThe balance dropped below your alert threshold.account.pausedAn account was paused by you or by its health score.import crypto from "node:crypto";
export function verify(rawBody, signature, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}Credits and limits
API, MCP and CLI actions cost exactly what they cost in the app: 3 credits per write. Reads cost 1 credit per 2 posts returned. The Safety Governor applies the same daily caps, burst limit and quiet hours. The API itself allows 120 requests a minute per key; over that you get 429 with a Retry-After header.
JavaScript SDK
npm install @xautomator/sdkimport { XAutomator } from "@xautomator/sdk";
const xa = new XAutomator({ apiKey: process.env.XAUTOMATOR_API_KEY });
const { credits } = await xa.estimate({ account_id: "acc_1", text: "New drop on Friday" });
const post = await xa.createPost({ account_id: "acc_1", text: "New drop on Friday" });
console.log(post.status, credits);Errors
Errors return a JSON body { "error": { "code": "...", "message": "..." } } with a matching status.
400 invalid_requestA field is missing or invalid.401 unauthorizedMissing, wrong or revoked key.402 no_creditsNot enough credits for this action.404 not_foundNo such account, post or rule.409 account_pausedThe account's kill switch is on.429 rate_limitedSlow down; see Retry-After.Ready to build?