API & MCP reference

Every request goes to https://withsynapse.app/api/v1 and carries your API key. Three steps to your first post:

1. Create a key on the API Keys page. It starts with syn_ and is shown once.
2. Find out what you can post to with GET /accounts.
3. Create the post.

# What can I post to?
curl https://withsynapse.app/api/v1/accounts \
  -H "Authorization: Bearer syn_your_key"

# Publish to every connected LinkedIn and Bluesky account
curl -X POST https://withsynapse.app/api/v1/posts \
  -H "Authorization: Bearer syn_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from the Synapse API.",
    "platforms": ["LinkedIn", "Bluesky"],
    "publish": true
  }'

Leave out publish to save a draft, or send scheduled_time to schedule it — Synapse publishes scheduled posts for you.

Send your key as a bearer token on every request. Keys are stored hashed, so a lost key cannot be recovered — create a new one and revoke the old one.

Authorization: Bearer syn_your_key

Your key carries the same power as your account: it can publish to your connected accounts and delete your posts. Keep it server-side, never commit it, and never ship it in a browser or mobile app. You can hold up to 25 keys and revoke any of them instantly from the API Keys page.

Limits are per account, per minute. A limited request returns 429 with a Retry-After header telling you how many seconds to wait.

Errors return a JSON body with a single error field written to be read by a human, and the matching HTTP status.

{
  "error": "`scheduled_time` must include an explicit timezone, e.g. 2026-08-01T09:00:00Z or 2026-08-01T17:00:00+08:00."
}

A post targets accounts, not platforms. Naming a platform is shorthand for “every account I have connected there”. If you have two Instagram accounts, "platforms": ["Instagram"] posts to both; use accounts with ids from GET /accounts to pick one.

Each account succeeds or fails on its own. One platform rejecting your post never blocks the others, and every account gets its own result with a live URL or an error message. That is why a post can end up partially_posted — and why retrying only re-attempts the failures.

Nothing is ever published twice. An account already recorded as posted is skipped on every subsequent publish or retry, and a post that is mid-publish rejects a second concurrent attempt with a 409.

Post statuses

Platform names

These strings are exact — including spacing and punctuation. Anything else is rejected with a list of the valid names.

Uploads happen in three steps so your file goes straight to storage instead of through this API — which means there is no size limit, and a several-hundred-megabyte video works fine. Ask for an upload URL, PUT the bytes to it, then record the result and use the returned path in media when you create a post.

# 1. Ask for an upload URL
RESP=$(curl -s -X POST https://withsynapse.app/api/v1/media \
  -H "Authorization: Bearer syn_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "launch.png", "content_type": "image/png" }')

PATH_=$(echo "$RESP" | jq -r .path)
URL=$(echo "$RESP" | jq -r .upload_url)

# 2. Upload the bytes straight to storage (no size limit)
curl -X PUT "$URL" -H "Content-Type: image/png" --data-binary @launch.png

# 3. Record it, then use the path in a post
curl -s -X POST https://withsynapse.app/api/v1/media/complete \
  -H "Authorization: Bearer syn_your_key" \
  -H "Content-Type: application/json" \
  -d "{\"path\":\"$PATH_\",\"filename\":\"launch.png\",\"content_type\":\"image/png\"}"

Accepted types are JPEG, PNG, WebP and GIF images, and MP4, MOV and WebM video. A post can carry up to 10 files.

The config object reaches every per-platform option the Synapse composer exposes. Every key is optional, and unknown keys are rejected so a typo never fails silently.

{
  "config": {
    "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE", "allow_duet": false },
    "youtube": { "title": "Synapse in 60 seconds", "privacy": "public" },
    "linkedin": { "visibility": "PUBLIC" },
    "cover": "…/1753790000-thumbnail.png",
    "firstComment": "Full changelog in the replies."
  }
}

Applies to every platform

Caption limits are enforced before anything is sent, counted the way each platform counts — X charges 23 characters for any link regardless of its real length. Per-platform overrides in captionsare checked against their own platform’s limit.

Add a webhook URL on the API Keys page and Synapse will POST there whenever a post finishes publishing — however it was created, including scheduled posts published while you were asleep. The URL must be HTTPS.

{
  "event": "post.completed",
  "timestamp": "2026-07-29T08:00:05.000Z",
  "post": {
    "id": "9f1c2e64-1a3b-4c8d-9e77-0b2f5a6d3c11",
    "status": "partially_posted",
    "results": {
      "abc123": {
        "status": "posted",
        "url": "https://www.linkedin.com/feed/update/...",
        "postedAt": "2026-07-29T08:00:04.000Z"
      },
      "you.bsky.social": {
        "status": "failed",
        "error": "Bluesky account isn't connected — reconnect it.",
        "postedAt": null
      }
    }
  }
}

Every delivery is signed with your webhook secret in the X-Synapse-Signature header, as sha256=<hex> over the raw request body. Verify it before trusting the payload, and always compare in constant time.

const crypto = require("crypto");

// Your signing secret is shown on the API Keys page.
function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  // Constant-time compare — never use ===, it leaks the secret byte by byte.
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/synapse-webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.get("X-Synapse-Signature"), process.env.SYNAPSE_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString());
  console.log(event.post.status);
  res.sendStatus(200);
});

Deliveries time out after 5 seconds and are not retried, so treat the webhook as a fast notification: acknowledge it immediately and do your work afterwards. It is a convenience, not a guarantee — GET /posts/{id} is always the source of truth.

MCP is how an AI assistant gets hands. Connect Synapse to an MCP client and you can stop describing posts and just ask for them — “post this to Instagram and X” — in any client that speaks the protocol: Claude, Cursor and others.

There are two servers and they share the same tools. Pick by where you want it to run:

Add this as a custom connector or remote MCP server in your client. There is nothing to install and no key to copy — your browser opens, you sign in to Synapse, you approve once, and the client is connected.

1. Paste the URL where your client asks for a connector or remote MCP server.
2. It sends you to Synapse. Sign in if you are not already, then read what the app is asking for and press Approve.
3. That is it — ask your assistant what accounts you have connected.

Behind the scenes this is standard OAuth 2.1 with PKCE, so any spec-compliant client handles it without Synapse-specific setup. Access is granted to that one app, for your account only, and you can withdraw it at any time.

Authorization: Bearer syn_your_key

The local server is an npm package that runs on your own computer. It is the right choice for one reason: because it runs where your files are, it can publish an image or video straight from a path on your disk.

Add this to your client’s MCP configuration — in Claude Desktop that is Settings → Developer → Edit Config — replacing the placeholder with a key from the API Keys page. Nothing to install first, since npx fetches it on demand. Quit and reopen the app fully afterwards, not just the window.

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-social-mcp"],
      "env": {
        "SYNAPSE_API_KEY": "syn_your_key_here"
      }
    }
  }
}

The package is synapse-social-mcp on npm.

Both servers expose the same tools, with one exception: upload_media takes a path on your computer, so only the local server can offer it. On the remote server, attach media that is already in your library instead — list_media gives you the paths.

Things to try

• Which social accounts do I have connected to Synapse?
• Schedule a LinkedIn post for Monday 9am Singapore time: “5 lessons from shipping in public”.
• Post the newest image in my Synapse media library to Instagram and X with the caption “Shipping day”.
• Post my demo video to TikTok and YouTube — make TikTok public and title the YouTube one “Synapse in 60 seconds”.
• Did anything fail to post this week? Retry just those.
• Post this to Instagram and X: “Shipping day” with the image at ~/Desktop/launch.png(local server only)

Every app you connect by URL is listed on your API Keys page under Connected apps, with when you connected it and when it last did anything. Press Disconnect and it loses access on its very next request.

An app can only ever do what your own account can do, and it is scoped to your account alone. Access renews itself while the app is in use and lapses on its own if it goes unused for 30 days. Anything already published stays published — disconnecting stops future posts, it does not retract past ones.

Skip this unless you are writing an MCP client yourself — an off-the-shelf client discovers all of it automatically. The endpoint is https://withsynapse.app/api/mcp, spoken as JSON-RPC over Streamable HTTP. It is stateless: no session id is issued, so every POST stands alone.

An unauthenticated request answers 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which is where discovery begins.

Clients are public clients: register with token_endpoint_auth_method: "none" and prove yourself with PKCE instead. Only S256 is accepted. Redirect URIs are matched by exact string against what you registered, so register every callback you will use — https anywhere, plain http only on localhost or 127.0.0.1, and private app schemes such as cursor:// are fine.

Access tokens last an hour and refresh tokens rotate on every use, so store the new refresh token each time and discard the old one.