Socialync API

Publish, schedule and read posts from your own code. It is the same publishing engine as the Socialync MCP server, over plain JSON. n8n, Make, Zapier, GitHub Actions and your own scripts can all call it with one key.

Base URL: https://mcp.socialync.io/v1. The machine readable spec (OpenAPI 3.1) is at https://mcp.socialync.io/v1/openapi.json.

Authentication

Create a key on the API keys page. It is the same key the MCP server uses, and it can be limited to some of your profiles. Send it as a bearer token. OAuth tokens are not accepted here.

Authorization: Bearer sk_live_...

Browsers cannot call the API: it sends no CORS headers. Keep keys on a server or in your CI secrets.

Quickstart

Check the key, your plan and your caps.

export SOCIALYNC_API_KEY=sk_live_...

curl https://mcp.socialync.io/v1/me \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY"

Publish now. Text and up to 10 images go to Facebook, Instagram, LinkedIn, X, Threads and Bluesky.

curl -X POST https://mcp.socialync.io/v1/posts \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "platforms": ["linkedin", "bluesky"],
    "caption": "Shipped from a script."
  }'

Schedule. With scheduledAt you can also post video and reach TikTok and YouTube.

# One hour from now (GNU date; on macOS use: date -u -v+1H +%Y-%m-%dT%H:%M:%SZ)
SCHEDULED_AT=$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)
curl -X POST https://mcp.socialync.io/v1/posts \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "platforms": ["instagram", "tiktok"],
    "caption": "Friday drop",
    "scheduledAt": "'"$SCHEDULED_AT"'",
    "mediaId": "upload:abc123",
    "tiktokPrivacyLevel": "PUBLIC_TO_EVERYONE"
  }'

Upload a file first when the media is not at a public URL.

# 1. Ask for an upload URL
curl -X POST https://mcp.socialync.io/v1/media \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"fileName":"launch.mp4","contentType":"video/mp4"}]}'

# 2. PUT the file to the uploadUrl in the answer, with the same Content-Type
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @launch.mp4

# 3. Finalize with the id from step 1. The answer holds the mediaId.
curl -X POST https://mcp.socialync.io/v1/media/$UPLOAD_ID/finalize \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY"

Quickstarts by language

The same three steps in each language: list your profiles, create a draft, schedule a post with an idempotency key. They are built from the OpenAPI document. A Postman collection of every endpoint is at https://mcp.socialync.io/v1/postman.json. Import it and paste your key into the apiKey variable.

curl

export SOCIALYNC_API_KEY=sk_live_...

# List your profiles
curl https://mcp.socialync.io/v1/profiles \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY"

# Create a draft (sends nothing)
curl -X POST https://mcp.socialync.io/v1/drafts \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platforms":["linkedin","bluesky"],"caption":"A draft made from a script."}'

# Schedule a post, with an idempotency key
# scheduledAt is one hour from now (GNU date; on macOS use: date -u -v+1H +%Y-%m-%dT%H:%M:%SZ)
SCHEDULED_AT=$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)
curl -X POST https://mcp.socialync.io/v1/posts \
  -H "Authorization: Bearer $SOCIALYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"platforms":["linkedin","bluesky"],"caption":"Scheduled from a script.","scheduledAt":"'"$SCHEDULED_AT"'"}'

JavaScript (fetch)

// Node 20 or later, in an ES module (.mjs). Keep the key in an environment variable or a CI secret.
const BASE = 'https://mcp.socialync.io/v1';
const headers = {
  Authorization: `Bearer ${process.env.SOCIALYNC_API_KEY}`,
  'Content-Type': 'application/json',
};

async function api(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers: { ...headers, ...init.headers } });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
  return body;
}

// List your profiles
const profiles = await api('/profiles');
console.log(profiles.data);

// Create a draft (sends nothing)
const draft = await api('/drafts', {
  method: 'POST',
  body: JSON.stringify({
    platforms: ['linkedin', 'bluesky'],
    caption: 'A draft made from a script.',
  }),
});
console.log(draft.id);

// Schedule a post, with an idempotency key
// scheduledAt is one hour from now. Send the same Idempotency-Key when you retry, so a retry cannot post twice.
const scheduled = await api('/posts', {
  method: 'POST',
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    platforms: ['linkedin', 'bluesky'],
    caption: 'Scheduled from a script.',
    scheduledAt: new Date(Date.now() + 3600e3).toISOString(),
  }),
});
console.log(scheduled.id, scheduled.status);

Python (requests)

import os
import uuid
from datetime import datetime, timedelta, timezone

import requests

BASE = 'https://mcp.socialync.io/v1'
HEADERS = {'Authorization': f"Bearer {os.environ['SOCIALYNC_API_KEY']}"}


def api(method, path, **kwargs):
    headers = {**HEADERS, **kwargs.pop('headers', {})}
    res = requests.request(method, BASE + path, headers=headers, timeout=120, **kwargs)
    body = res.json()
    if not res.ok:
        err = body['error']
        raise RuntimeError(f"{res.status_code} {err['code']}: {err['message']}")
    return body


# List your profiles
profiles = api('GET', '/profiles')
print(profiles['data'])

# Create a draft (sends nothing)
draft = api('POST', '/drafts', json={
    'platforms': ['linkedin', 'bluesky'],
    'caption': 'A draft made from a script.',
})
print(draft['id'])

# Schedule a post, with an idempotency key
# scheduledAt is one hour from now. Send the same Idempotency-Key when you retry, so a retry cannot post twice.
scheduled = api(
    'POST',
    '/posts',
    headers={'Idempotency-Key': str(uuid.uuid4())},
    json={
        'platforms': ['linkedin', 'bluesky'],
        'caption': 'Scheduled from a script.',
        'scheduledAt': (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat(),
    },
)
print(scheduled['id'], scheduled['status'])

How publishing works

• A call with your key is your instruction. POST /v1/posts publishes without a confirmation step. If you switched on the publish confirmation in your Socialync settings, both POST /v1/posts and approving a draft answer 403 direct_publish_disabled. Turn that setting off to publish through the API. Creating a draft still works.
• To hold a post for a person to approve, use POST /v1/drafts and then POST /v1/drafts/{id}/approve. A draft nobody approves expires after 24 hours.
• Content written or made by an AI model must be approved by a person before it is scheduled or published. Send it as a draft and let the account owner approve it. Section 10 of the Developer Agreement covers this, and the agreement applies to every call.
• An immediate post is text and images. Video, TikTok and YouTube need scheduledAt, a few minutes ahead or later.
• imageUrls and videoUrl are copied into Socialync storage when you schedule, so a link only has to work at that moment.
• The monthly allowance of your plan, the daily post cap per profile, the platforms' own limits and the X and YouTube rules are the same as in the app and the MCP server. Posts to several platforms count once against the daily cap.
• When some platforms publish and some fail, the status is 207 and results says which.
• Add ?view=history to GET /v1/posts for finished multi platform posts. Scheduled posts keep the id the create call returned.

Limits and retries

• 60 requests per minute per key. Past that you get 429 with Retry-After. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
• Each key can have 5 requests running at once. The service also caps the total across all keys. Past either cap you get 429 with Retry-After. Wait for a running request to finish before you send the next.
• Request bodies are limited to 256 KB. Images do not go in the body. Upload them with POST /v1/media or pass a URL.
• Send an Idempotency-Key header on every POST you might retry. The same key with the same body returns the first response for 24 hours, so a retry cannot post twice. The same key with a different body is a 422.
• A request that is refused (a 4xx) frees its key, so you can fix the body and send it again with the same key. A request that ends in a 500 or 504 may still have gone out, so the key keeps returning that answer. Check GET /v1/posts, then use a new key. If the API could not record the result of a request, the key answers 409 idempotency_outcome_unknown until it expires and does not run the request again.
• Lists return 20 items by default, at most 100. Pass the nextCursor from a response as cursor to get the next page.

Errors

Every error has the same shape. Switch on error.code. The message is for people and can change.

{
  "error": {
    "code": "daily_cap_reached",
    "message": "Daily draft cap reached: 10 drafts per UTC day per profile on this plan.",
    "docs": "https://www.socialync.io/developers/api#daily_cap_reached"
  }
}

Endpoints

Request and response schemas for every endpoint are in the OpenAPI document.