SocialStudio API MCP setup Get an API key

SocialStudio API

Everything the app does, from your own code or your AI assistant: write and generate posts, attach media, schedule and publish, build carousels and scripts, run your idea pipeline, read analytics, and work the inbox.

Quickstart

Create a key in the app under Settings, API Keys. It is shown once. Then make a request:

Check the key works
curl /api/v1/me \
  -H "Authorization: Bearer ss_live_YOUR_KEY"

Create a draft, then schedule it to a connected account:

Draft, then schedule
# 1. the accounts you can publish to
curl /api/v1/platforms -H "Authorization: Bearer $KEY"

# 2. a draft from your own caption
curl -X POST /api/v1/posts \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Launch day", "caption": "We are live.", "media_urls": ["https://example.com/hero.png"]}'

# 3. schedule it (use the task_id from step 2 and a platform_id from step 1)
curl -X POST /api/v1/posts/TASK_ID/schedule \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-day-1" \
  -d '{"platform_ids": ["PLATFORM_ID"], "scheduled_at": "2026-12-01T14:30:00+05:30"}'

Authentication

Every request carries a personal API key as a bearer token. Keys start with ss_live_.

Header
Authorization: Bearer ss_live_…
  • A key acts as you, with your credits, plan and workspace permissions.
  • Only a hash of the key is stored. If you lose it, rotate it or make a new one.
  • Keys can expire, can be limited to scopes, and can be revoked at any time. All three take effect immediately.
  • Keys are managed in the app while signed in. A key cannot create or change keys.
  • The API does not read the browser's session cookie, so it cannot be driven from another site.

Scopes

A key has full access, or a list of scopes. Each scope is a group and a level: posts:read or posts:write. Write includes read. Every operation below names the one scope it needs; a key without it gets 403 insufficient_scope.

ScopeReadWrite adds

A scoped key works on this API and on the MCP server only. An operation marked needs a full-access key, such as chatting with the assistant, cannot be run by a scoped key at all, because it can act across every area.

Errors

A failed request has a matching HTTP status and one body shape. Branch on code, show message, and quote request_id if you ask us for help.

Error body
{
  "error": {
    "code": "insufficient_credits",
    "message": "You need at least 5 credits to generate an image.",
    "request_id": "req_3f9a…"
  }
}
StatusCodeMeaning
400invalid_request, unknown_parameter, missing_parameter, invalid_jsonThe request is malformed. The message says which field.
401unauthorized, invalid_api_keyNo key, or a key that is revoked or expired.
402insufficient_creditsNot enough credits for this operation.
403insufficient_scope, forbiddenThe key lacks the scope, or your plan or role does not allow it.
404not_foundNo such resource on this account.
409conflict, idempotency_in_progressThe resource is busy, or the same request is still running.
422validation_error, idempotency_key_reusedA field has the wrong type or value. details lists each one.
429rate_limitedSlow down. Wait for Retry-After seconds.
5xxinternal_error, timeoutOur side. A 504 timeout was not cancelled: read the resource before retrying.

Rate limits

Each key may make 120 requests a minute. Operations that use credits share a tighter allowance of 30 a minute per account. Every response reports where you stand:

Response headers
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Window: 60
X-Request-Id: req_3f9a…

Over the limit you get 429 with a Retry-After header in seconds.

Idempotency

A network error leaves you unsure whether a publish went through. Send an Idempotency-Key header (any unique string, up to 255 characters) on a write, and retry with the same key: the first answer is stored for 24 hours and replayed, with Idempotent-Replayed: true, instead of the work running twice.

  • The same key with a different body is refused with 422 idempotency_key_reused.
  • A retry while the first request is still running gets 409 idempotency_in_progress.
  • Use it on anything that publishes, sends or spends: scheduling, publishing, sending a message, generation.

Workspaces and ids

A workspace groups connected social accounts and its own content. Most operations take an optional workspace_id; without it they use your Default workspace. A post's id is its task_id; a connected account's id is its platform_id.

Request bodies are JSON. Date-times are ISO 8601; a time with no offset is read as Asia/Kolkata. Unknown fields are refused rather than ignored, so a typo fails loudly.

Long-running work

Generation can take longer than one request should. These operations start the work and tell you how to follow it:

  • Carousels. POST /carousels waits up to wait_seconds, then returns the carousel or status: "generating". Read GET /carousels/{id}?wait_seconds=60 until it is completed.
  • Creative Studio. Image and video requests return a job. Read GET /creative/jobs/{job_id} until it is done.
  • Outliers and Daily Trend. A refresh or a run starts in the background; read the feed or the status.

If a request times out with 504, the work was not cancelled. Read the resource back before trying again.

MCP server

The same operations are available to AI assistants as tools, over the Model Context Protocol (Streamable HTTP).

Server URL
/mcp
Claude Code
claude mcp add --transport http social-studio /mcp \
  --header "Authorization: Bearer ss_live_YOUR_KEY"
Cursor and other clients with a JSON config
{
  "mcpServers": {
    "social-studio": {
      "url": "/mcp",
      "headers": { "Authorization": "Bearer ss_live_YOUR_KEY" }
    }
  }
}

ChatGPT and Claude on the web connect by sign-in instead: add the URL as a connector and approve access.

An assistant sees named tools for the common jobs, and three tools that reach everything else: search_api finds an operation, describe_api_operation shows its inputs, and call_api runs it. A scoped key only sees the tools its scopes allow.

ToolWhat it does

Reference

Base URL .

Kept in this browser tab only and sent only to this site. Requests run against your real account.

Loading the reference…