PostBaton

Schedule social posts to X, Bluesky, Mastodon, LinkedIn, TikTok, Telegram and more.

Hosted MCP Server

npx add-mcp 'https://api.postbaton.com/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Schedule to every network you connect, from your own code or from an assistant.

PostBaton has a REST API and an MCP server, and both sit on the same publishing engine as the app. So a post you send from a script is handled like one you clicked: before any retry the engine checks the network for it, and if it gives up you can see why.

1 token · 1 JSON shape · 12 networks supported, 7 open to everyone today · opt-in Idempotency-Key

# 1. list your workspaces, 2. list its accounts,
# 3. schedule a post to the account ids you got back.
curl https://api.postbaton.com/v1/workspaces \
  -H "Authorization: Bearer pbt_your_token"
import requests
H = {"Authorization": "Bearer pbt_your_token"}
ws = requests.get("https://api.postbaton.com/v1/workspaces", headers=H).json()
wid = ws["workspaces"][0]["workspace_id"]
accts = requests.get(f"https://api.postbaton.com/v1/workspaces/{wid}/accounts", headers=H).json()
const H = { Authorization: "Bearer pbt_your_token" };
const base = "https://api.postbaton.com/v1";

const ws = await fetch(\`${base}/workspaces\`, { headers: H }).then(r => r.json());
const wid = ws.workspaces[0].workspace_id;

The full request and response shapes live in the OpenAPI spec. Generate a snippet from your own post.

Three calls, one post

A post targets accounts, not networks, so you look up the account ids once and reuse them. Here is the whole loop.

# Schedule, then read it back, then cancel if you need to.
curl https://api.postbaton.com/v1/workspaces/$WID/posts \
  -H "Authorization: Bearer pbt_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: friday-doors-open" \
  -d '{
    "body": "Doors open Friday at 7.",
    "scheduled_at_epoch": 1790000000,
    "timezone": "America/New_York",
    "targets": [{ "social_account_id": "'"$ACCT"'" }]
  }'

curl "https://api.postbaton.com/v1/workspaces/$WID/posts?limit=20" \
  -H "Authorization: Bearer pbt_your_token"

curl -X POST \
  https://api.postbaton.com/v1/workspaces/$WID/posts/$POST_ID/cancel \
  -H "Authorization: Bearer pbt_your_token"
base = f"https://api.postbaton.com/v1/workspaces/{WID}"

post = requests.post(f"{base}/posts", headers={
    **H, "Idempotency-Key": "friday-doors-open",
}, json={
    "body": "Doors open Friday at 7.",
    "scheduled_at_epoch": 1790000000,
    "timezone": "America/New_York",
    "targets": [{"social_account_id": ACCT}],
}).json()

requests.get(f"{base}/posts?limit=20", headers=H)
requests.post(f"{base}/posts/{post['post_id']}/cancel", headers=H)

One shape for a post to any network.

Base and auth

Every call is under https://api.postbaton.com/v1 and carries a bearer token: Authorization: Bearer pbt_.... You make a token in the app under API tokens. It acts as you, so it can do what you can do and nothing more, and revoking it takes effect on the very next request.

A post is body plus targets

Send a body and a list of targets, each naming one connected account. Set scheduled_at_epoch and timezone to schedule it, or leave the time off to save a draft. Give any target its own body to say something different on that network. Attach images or video by adding media.

{
  "body": "Same idea, two audiences.",
  "scheduled_at_epoch": 1790000000,
  "timezone": "UTC",
  "targets": [
    { "social_account_id": "acct_linkedin" },
    { "social_account_id": "acct_bluesky",
      "body": "Same idea, fewer suits. 🧪" }
  ],
  "media": [{ "storage_key": "media_from_upload_url" }]
}
# The ones you reach for most
GET  /v1/workspaces
GET  /v1/workspaces/{id}/accounts
POST /v1/workspaces/{id}/posts            # schedule or draft
GET  /v1/workspaces/{id}/posts            # cursor paginated
POST /v1/workspaces/{id}/posts/{pid}/cancel
POST /v1/workspaces/{id}/posts/{pid}/reschedule
POST /v1/workspaces/{id}/posts/bulk       # many at once
POST /v1/workspaces/{id}/media/upload-url # attach media
GET  /v1/workspaces/{id}/webhooks         # your webhook subscriptions
GET  /v1/workspaces/{id}/catches          # X catches and score

Agent-ready, without handing over the keys.

Point any MCP client at https://api.postbaton.com/mcp with your token and it can schedule for you. The tool list is short on purpose, because every capability you hand an assistant is one it might use at the wrong moment.

  • List your workspaces
  • List a workspace's connected accounts
  • Schedule a post, to one account or many
  • List posts, so it can tell you what went out and what failed
  • Cancel a post that has not gone out yet
  • Edit a post that has not gone out yet: its text, time, accounts, media or first comment
  • Schedule up to 100 posts in one call
  • List the media library, including audio tracks to add to a video
  • Read when an account's own past posts did best
  • Read every account's followers, profile views and posts per week
  • Read X catches: drafted replies, account score and stage

It cannot connect an account, buy credits, change your plan, invite anyone, or reach a workspace you are not in. An X post it schedules uses a credit, the same as one you schedule yourself. If you want the whole story, the MCP explainer walks through it, and the help page for AI assistants is the reference.

  • Claude Desktop
  • Claude Code
  • Cursor
  • Windsurf
  • Codex
  • Any MCP client
claude mcp add --transport http postbaton \
  https://api.postbaton.com/mcp \
  --header "Authorization: Bearer pbt_your_token"

# check it: run /mcp and look for "connected"
{
  "mcpServers": {
    "postbaton": {
      "type": "http",
      "url": "https://api.postbaton.com/mcp",
      "headers": {
        "Authorization": "Bearer pbt_your_token"
      }
    }
  }
}
# plain language, the assistant fills in the ids
"Schedule this to our Bluesky and Mastodon
 for Thursday at 9am Eastern: ..."

"What have we got queued for next week?"

"Cancel the Friday LinkedIn post."

Automation should remove things to watch, not add one.

Dedup when you ask for it

Send an Idempotency-Key header with POST /posts and a repeat of a request that succeeded, within 24 hours, gets the first response back instead of making a second post. A repeat that arrives while the first is still running gets a 409, and the same key with a different body gets a 422. It is opt-in and only that call reads it, so without the header two identical calls make two posts, and if the key store is unavailable the request goes through unguarded. The MCP tools take no key, so an assistant that retries a timed-out schedule call can create a second post; ask it to list posts before it tries again.

Failures you can read

A delivery that gives up lands in Failed deliveries with a typed reason, the same one the app shows and the email sends, whether a person or a cron job scheduled it. The failure reference lists the codes, and the reliability page lists the few cases that are quieter than that.

Webhooks, not polling

Register a webhook and PostBaton calls it when a delivery publishes or fails, so your system learns about a problem without asking every minute whether anything went wrong. Two failures do not send one yet: a delivery that runs out its three-day wait for credits, and a TikTok video that TikTok rejects while processing it, after the delivery was already reported as published.

Two tools that run in your browser.

Paste a caption into the limit checker and see what fits on each network before you write a line of code. Or use the snippet generator to turn a post into a runnable cURL, Python, or MCP call. Neither sends anything anywhere, and neither posts.