Socifyr REST API reference ​

The REST API is what the dashboard, SDKs, CLI and MCP server all call. Every endpoint is under https://api.socifyr.com/api, takes and returns JSON (file uploads use multipart/form-data), and wraps results in the same envelope. For a self-hosted install, use your own host.

How do I authenticate to the Socifyr API? ​

Send an API key as a bearer token:

Authorization: Bearer sk_4b73...

Create keys under API keys in the dashboard or with the API keys endpoints. A key belongs to one workspace, so the workspace is known from the key and acts with the workspace owner's role.

Dashboard session tokens (JWT) also work as bearer tokens. A session user can belong to several workspaces, so send the one to act on:

X-Workspace-Id: 6a04f0000000000000000001

Without X-Workspace-Id, a session request uses the first workspace the user joined. More in API keys and Workspace header.

What does a response look like? ​

Every success is wrapped:

{ "success": true, "data": <result> }

Some DELETE routes return 204 with no body, and GET /analytics/export returns raw CSV. Every other route uses the envelope.

Errors use one shape:

{
  "success": false,
  "error": "Connection \"nonexistent-slug\" not found or not active. Check your connections page for valid slugs.",
  "statusCode": 400,
  "path": "/api/content/text",
  "timestamp": "2026-11-13T09:00:00.000Z"
}

Validation failures return error as an array of strings:

{
  "success": false,
  "error": ["connections must be an array", "text must be shorter than or equal to 25000 characters"],
  "statusCode": 400,
  "path": "/api/content/text",
  "timestamp": "2026-11-13T09:00:00.000Z"
}

Server errors (5xx) also include a requestId in the body. Responses carry an X-Request-Id header. Quote it when you contact support.

The API rejects unknown body fields with 400, so send only documented fields.

Which status codes should I handle? ​

The full list with fixes is in Errors.

What are the rate limits? ​

The default is 60 requests per minute. The limit is counted per workspace for API keys and per user for session tokens. Some routes differ:

A rate-limited request returns 429. Plan limits (posts, accounts, storage) are separate and return 403. See Limits.

How do I avoid duplicate posts when I retry? ​

Send an Idempotency-Key header on a POST. X-Idempotency-Key and X-Request-Id are also read. A repeat of the same key in the same workspace returns the first response instead of creating another post.

Which endpoints exist? ​

Other routes: GET /users/me returns the signed-in user with their workspaces and works with any key. GET /status is public and returns anonymized per-platform publish success rates from the last 24 hours.

Is there an OpenAPI spec? ​

The hosted production API does not serve Swagger. A non-production or self-hosted development build serves it at /api/docs. These pages are written from the same controllers and validation rules.

Can I use the API without writing HTTP code? ​

Yes. The same operations are available in the TypeScript and Python SDKs, the CLI and the MCP server.

Versioning ​

The API is unversioned. Breaking changes ship as new endpoints, not by changing existing ones. Watch the releases for additions.

Next steps ​

• Content API to publish your first post
• Connections API to find slugs and check account health
• API keys and guardrails before you give a key to an agent
• Quickstart