Getting Started

BetterPost is one REST API (and an MCP server) for publishing and scheduling posts to X, LinkedIn, Instagram and Facebook. Every account starts in the sandbox: the API behaves exactly as it will in production (validation, credits, webhooks, scheduling), but nothing is sent to the real networks.

Base URLCopy Anchor Link

https://api.betterpost.dev/v1

All requests and responses are JSON. Every response carries the header x-betterpost-mode: sandbox.

1. Create an API keyCopy Anchor Link

Sign in at betterpost.dev, open Dashboard → API keys and create a key. Keys look like sk_test_ followed by 32 letters and digits. The full key is shown once; BetterPost only stores a hash of it.

export BETTERPOST_API_KEY=sk_test_your_key_here

Check that the key works:

curl -s https://api.betterpost.dev/v1/health/auth \
  -H "x-access-key: $BETTERPOST_API_KEY"

{ "ok": true }

2. Connect a social accountCopy Anchor Link

Ask for a connect URL and open it in a browser. In the sandbox it leads to a simulated consent screen where you pick any handle and click Authorize.

curl -s "https://api.betterpost.dev/v1/connect/twitter" \
  -H "x-access-key: $BETTERPOST_API_KEY"

{ "url": "https://betterpost.dev/sandbox/authorize?state=Qm3x9TzK2pV8wLr4nB6yHc1dF7gJ0sAeUoXiZtNq" }

Repeat for linkedin, then list your accounts to get their ids:

curl -s https://api.betterpost.dev/v1/connect/integrations \
  -H "x-access-key: $BETTERPOST_API_KEY"

Each integration's id (for example acc_2x9c4v7b1n8m3k5j0h6g2f4d) is the accountId you post to. See Connect an account.

3. Publish a postCopy Anchor Link

curl -s -X POST https://api.betterpost.dev/v1/posts \
  -H "x-access-key: $BETTERPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from BetterPost",
    "platforms": [
      { "platform": "twitter", "accountId": "acc_2x9c4v7b1n8m3k5j0h6g2f4d" },
      { "platform": "linkedin", "accountId": "acc_5l1n7k3j9h2g8f4d6s0a1q3w" }
    ],
    "publishNow": true
  }'

The API answers 202 Accepted with the overall status and one result per target:

{
  "success": true,
  "status": "published",
  "postId": "post_8f3k2m9q1x7v4n6b0c5d2a1z",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_2x9c4v7b1n8m3k5j0h6g2f4d",
      "success": true,
      "platformPostUrl": "https://betterpost.dev/sandbox/p/twitter/sbx_1849203756184930275"
    },
    {
      "platform": "linkedin",
      "accountId": "acc_5l1n7k3j9h2g8f4d6s0a1q3w",
      "success": true,
      "platformPostUrl": "https://betterpost.dev/sandbox/p/linkedin/sbx_6620194837561029384"
    }
  ]
}

Open a platformPostUrl to see a preview of the simulated post. This post cost 6 credits: 5 for X and 1 for LinkedIn (see Credits).

Next stepsCopy Anchor Link

• Sandbox mode: force failures, warnings and slow publishes with test triggers.
• Schedule a post for later, in any time zone.
• Webhooks: get notified when posts publish or fail.
• Platform guides: limits and options for each network.
• MCP server: let Claude, Cursor or Codex post for you.
• API reference: every endpoint, field and status code.