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.
/api/v1, with an OpenAPI document.
MCP serverThe same operations as tools for Claude, ChatGPT and Cursor.
OpenAPI 3.1Generate a client, or import it into Postman.
Quickstart
Create a key in the app under Settings, API Keys. It is shown once. Then make a request:
curl /api/v1/me \
-H "Authorization: Bearer ss_live_YOUR_KEY"Create a draft, then schedule it to a connected account:
# 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_.
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.
| Scope | Read | Write 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": {
"code": "insufficient_credits",
"message": "You need at least 5 credits to generate an image.",
"request_id": "req_3f9a…"
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request, unknown_parameter, missing_parameter, invalid_json | The request is malformed. The message says which field. |
| 401 | unauthorized, invalid_api_key | No key, or a key that is revoked or expired. |
| 402 | insufficient_credits | Not enough credits for this operation. |
| 403 | insufficient_scope, forbidden | The key lacks the scope, or your plan or role does not allow it. |
| 404 | not_found | No such resource on this account. |
| 409 | conflict, idempotency_in_progress | The resource is busy, or the same request is still running. |
| 422 | validation_error, idempotency_key_reused | A field has the wrong type or value. details lists each one. |
| 429 | rate_limited | Slow down. Wait for Retry-After seconds. |
| 5xx | internal_error, timeout | Our 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:
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 /carouselswaits up towait_seconds, then returns the carousel orstatus: "generating". ReadGET /carousels/{id}?wait_seconds=60until it iscompleted. - 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).
/mcpclaude mcp add --transport http social-studio /mcp \
--header "Authorization: Bearer ss_live_YOUR_KEY"{
"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.
| Tool | What 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…