Build on Refract: API, MCP, CLI and webhooks

The Refract API lets your scripts and apps read workspaces, accounts and posts, create drafts, schedule them and add files. It speaks JSON:API at https://refract.social/api/v1, with tokens that act as an Editor, Contributor or Viewer in the workspaces you pick, and posts to 10 networks today: Pinterest, Bluesky, Mastodon, Telegram, WordPress, Discord, Tumblr, Slack, Pixelfed and DEV.
Base URLhttps://refract.social/api/v1

A draft, then a schedule.

Two requests: create a draft for an account, then schedule it. Where the workspace asks for approval from tokens, the second one sends it for approval instead.

  1. Create a draft

    bash
    curl -X POST https://refract.social/api/v1/workspaces/kolo-coffee/posts \
  -H "Authorization: Bearer rf_live_…" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "posts",
    "attributes": {
      "text": "Fresh Guji on the bar today.",
      "accounts": [
        "0199e2a5-0a33-7d1e-8c4f-5b2a9e7d1c10"
      ]
    }
  }
}'

  2. Schedule it

    bash
    curl -X POST https://refract.social/api/v1/workspaces/kolo-coffee/posts/{post}/schedule \
  -H "Authorization: Bearer rf_live_…" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "posts",
    "attributes": {
      "when": "at",
      "at": "2026-11-03T09:00:00+01:00"
    }
  }
}'

Tokens with a role.

What a token can do, by its role
RoleWhat it can do
EditorReads everything, creates drafts, schedules and publishes, deletes posts.
ContributorReads everything, creates drafts and sends them for approval, deletes its own drafts. Can't publish.
ViewerReads workspaces, accounts, posts and files. Changes nothing.

Everything you can build on.

  • API reference

    Authentication, every endpoint, post fields per network, files and errors.

    Open API reference

  • MCP server

    Let Claude, ChatGPT, Cursor or VS Code draft and schedule posts, with your approval if you want it.

    Open MCP server

  • Webhooks

    Hear when a post is queued, published, failed, edited or removed, or waits for approval. Signed, with retries.

    Open Webhooks

  • Rate limits

    120 requests a minute per token, with headers that say where you stand.

    Open Rate limits

  • CLI

    Post from your terminal: <code>npm install -g @refract/cli</code>, then <code>refract login</code>. No token to paste.

    Open CLI

On every plan

The API, the MCP server and webhooks are on every plan, from $10 a month, with a 14-day free trial.

Write it once, native everywhere.

Start a free trial, create a token in Settings › API and agents, and send your first request.

Start free trialRead the API docs

No card needed