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.

Quickstart

  1. Create an API key in Developers, API keys. Keys start with xa_live_. They are shown once, so store yours in a password manager.
  2. Pick how you want to work: give the agent install prompt to your AI agent, install the CLI, or call the REST API.
  3. Check the cost first. POST /estimate, xa estimate and the xa_estimate_cost tool are free.
Your first request
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.

Header
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 Code
claude mcp add xautomator --scope user -e XAUTOMATOR_API_KEY=xa_live_... -- npx -y @xautomator/mcp
Claude Desktop, Cursor, Windsurf (mcpServers)
{
  "mcpServers": {
    "xautomator": {
      "command": "npx",
      "args": [
        "-y",
        "@xautomator/mcp"
      ],
      "env": {
        "XAUTOMATOR_API_KEY": "xa_live_..."
      }
    }
  }
}
Tools
xa_whoamiWho is signed in, and whether the server runs on mock data
xa_list_accounts / xa_get_accountConnected accounts, health, approval mode
xa_pause_account / xa_resume_accountKill switch for one account
xa_update_safetyApproval mode, quiet hours and daily caps
xa_estimate_costCredit cost before posting, plus the balance
xa_create_postSchedule a post, thread or poll, or save a draft
xa_list_posts / xa_get_post / xa_update_postRead and edit the queue
xa_cancel_post / xa_send_post_nowCancel or send now (needs confirm)
xa_list_approvals / xa_approve / xa_rejectWork the approval queue
xa_list_rotations / xa_create_rotation / xa_update_rotation / xa_delete_rotationProfile Studio
xa_list_boost_rules / xa_create_boost_ruleAuto plug and auto repost
xa_get_balance / xa_get_ledgerCredits
xa_get_audit / xa_get_analytics / xa_list_alertsWhat happened and how it is going
xa_create_webhookSend events to your own endpoint

Prompts: 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.

Copy this prompt into your agent
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/docs

CLI 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.

Install
npm install -g xautomator
xa login
xaOpen the terminal dashboard
xa loginSave your API key (stored with read access for you only)
xa accountsList connected X accounts
xa post "Launch day" --thread "Here is why" --at 2026-11-25T09:30:00ZSchedule a thread
xa estimate "New drop https://..."Credit cost before posting
xa queue --status waitingThe queue, filtered
xa approvals / xa approve <id>Work the approval queue
xa pause <account>Kill switch
xa credits --ledgerEvery credit in and out
xa audit --limit 20Recent actions
xa mcpPrint MCP setup for your agent

Add --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": [...] }.

Accounts
GET/meThe signed in user, plan and number of accounts.
GET/accountsEvery connected X account with health, paused state and approval mode.
GET/accounts/{id}One account's full settings.
PATCH/accounts/{id}Update approval_mode, quiet_hours or daily_caps.
POST/accounts/{id}/pauseKill switch. Pauses every scheduled and automated action.
POST/accounts/{id}/resumeResume a paused account.
Posts
POST/estimateCredit cost of a post or thread. Free.
POST/postsSchedule a post, thread or poll. Omit schedule_at to use the next free time slot.
GET/postsThe queue. Filter with status and account_id.
GET/posts/{id}One post with its status and the reason it is waiting or blocked.
PATCH/posts/{id}Edit the text, thread or time of an unsent post.
DELETE/posts/{id}Cancel a post. Costs nothing.
POST/posts/{id}/sendSend a queued post now. Passes the Safety Governor and costs credits.
Approvals
GET/approvalsActions waiting for approval, with the reason and expiry.
POST/approvals/{id}/approveApprove and send. Pass always_allow_rule to trust the rule from now on.
POST/approvals/{id}/rejectReject. Nothing is sent and no credits are used.
Profile Studio
GET/rotationsBio, name, location, website, avatar, banner and pinned post rotations.
POST/rotationsCreate a rotation. First run waits for approval.
PATCH/rotations/{id}Pause, resume or edit a rotation.
DELETE/rotations/{id}Delete a rotation.
Boost
GET/boost-rulesAuto plug, auto repost and auto delete rules.
POST/boost-rulesCreate a rule. Runs once per post.
Credits
GET/creditsPlan and pack balance.
GET/credits/ledgerEvery credit in and out.
Insights
GET/auditRecent actions with status, credits and trace.
GET/analyticsFollowers, growth, posts, average likes and credits spent for ?days=.
GET/alertsApprovals waiting, failures, low credits and health warnings.
Webhooks
GET/webhooksYour webhook endpoints.
POST/webhooksAdd an endpoint. Returns the signing secret once.
DELETE/webhooks/{id}Remove an endpoint.
Schedule a thread
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"
  }'
Response
{
  "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.
Verify a signature (Node.js)
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

Install
npm install @xautomator/sdk
index.js
import { 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.