API Reference

Base URL

https://api.social-api.ai/v1

Authentication

All endpoints require a Bearer token. The API accepts three token types:

Token type	Format	Use case
API key	`sapi_key_...`	External API clients
Auth service JWT	EdDSA signed JWT	Dashboard frontend
OAuth 2.1 access token	EdDSA signed JWT	MCP / AI assistant clients

Authorization: Bearer sapi_key_your_key_here

See the Authentication guide for how to create and manage keys.

Request format

All request bodies must be JSON with Content-Type: application/json
All timestamps are RFC 3339 (e.g. 2026-02-15T14:30:00Z)
Paginated endpoints accept limit (1-100, default varies by endpoint, 20 or 25), cursor, and filtering parameters. The previous response’s next_cursor field is what you pass back as cursor.

Response format

All successful responses are JSON. All errors use:

{
  "error": {
    "code": "namespace.specific_code",
    "message": "human-readable message",
    "meta": { "field": "..." }
  }
}

See Errors for the full code catalog. Notable status codes:

HTTP status	Meaning
`400`	Invalid request parameters
`401`	Invalid or missing API key
`403`	Feature not available on your plan
`404`	Account or resource not found
`409`	Account already linked
`410`	Resource gone (expired invite, closed reply window)
`412`	BYOK credentials missing
`413`	Storage quota exceeded
`429`	Monthly resource limit or upstream platform rate limit hit
`501`	Platform does not support this operation

Endpoint groups

Group	Endpoints	Description
Accounts	`GET /accounts`, `POST /accounts/connect`, `DELETE /accounts/:id`, `GET /accounts/:id/creator-info`, `GET /accounts/:id/pages`, `PATCH /accounts/:id/pages/:pageId`, `GET /accounts/:id/limits`	Connect, list, and disconnect social accounts; manage pages and per-account creator info
Brands	`GET /brands`, `POST /brands`, `PATCH /brands/:id`, `DELETE /brands/:id`	Manage workspaces (brands)
Invites	`GET /invites`, `POST /invites`, `DELETE /invites/:id`	Brand invite tokens
Inbox - Comments	`GET /inbox/comments`, `GET /inbox/comments/:postId`, `GET /inbox/comments/:postId/:commentId/replies`, `POST /inbox/comments/:postId`, `DELETE /inbox/comments/:postId/:commentId`, `POST .../hide`, `DELETE .../hide`, `POST .../like`, `DELETE .../like`, `POST .../private-reply`	List commented posts and replies, reply, moderate (hide, like, delete, private reply)
Inbox - Conversations	`GET /inbox/conversations`, `GET /inbox/conversations/:id`, `PATCH /inbox/conversations/:id`, `GET .../messages`, `POST .../messages`, `POST .../read`	List conversations, read and send DMs, mark as read
Inbox - Reviews	`GET /inbox/reviews`, `POST /inbox/reviews/:id/reply`	Read reviews and reply
Mentions	`GET /accounts/:id/mentions`	Read mentions for a connected account
Publishing	`POST /posts`, `GET /posts`, `GET /posts/:pid`, `PATCH /posts/:pid`, `DELETE /posts/:pid`, `POST /posts/:pid/retry`, `POST /posts/:pid/unpublish`, `GET /posts/:pid/metrics`, `POST /posts/import`, `GET /posts/validate`, `POST /posts/validate`	Create, schedule, update, delete, retry, and monitor posts
Media Library	`GET /media`, `DELETE /media/:id`, `GET /media/storage`, `GET /media/upload-url`, `POST /media/upload`, `POST /media/:id/verify`	Upload, list, delete media files and check storage
Exports	`POST /accounts/:id/export`, `GET /exports`, `GET /exports/:id`, `GET /exports/:id/videos`	Run and read analytics exports
Events	`GET /events`, `GET /events/summary`	Unified events log
Usage	`GET /usage`	Check workspace plan usage
API Keys	`GET /keys`, `POST /keys`, `DELETE /keys/:id`	Manage API keys
Webhooks	`GET /webhooks`, `POST /webhooks`, `GET /webhooks/:id`, `PATCH /webhooks/:id`, `DELETE /webhooks/:id`, `POST /webhooks/:id/test`, `GET /webhooks/:id/deliveries`, `GET /webhooks/:id/deliveries/:did`, `POST /webhooks/:id/deliveries/:did/retry`, `GET /webhooks/events`	Manage outbound webhook endpoints, inspect deliveries, list event catalog
OAuth redirect URIs	`GET /oauth/redirect-uris`, `POST /oauth/redirect-uris`, `DELETE /oauth/redirect-uris/:id`	Manage the OAuth redirect URI whitelist (dashboard only)
Twitter BYOK	`GET /platforms/twitter/credentials`, `PUT /platforms/twitter/credentials`, `PUT /platforms/twitter/credentials/brand/:brand_id`, `DELETE /platforms/twitter/credentials`, `DELETE /platforms/twitter/credentials/brand/:brand_id`, `POST /platforms/twitter/credentials/test`	Manage your Twitter / X developer app credentials
WhatsApp	`POST /platforms/whatsapp/phone-numbers/:id/request-code`, `POST .../verify-code`, `POST .../register`, `POST .../deregister`, `GET .../status`, `GET .../business-profile`, `PUT .../business-profile`, `GET /platforms/whatsapp/accounts/:id/templates`, `POST .../templates`, `DELETE .../templates`, `GET /platforms/whatsapp/templates/:id`, `PUT /platforms/whatsapp/templates/:id`, `POST /platforms/whatsapp/accounts/:id/send-template`	Manage WhatsApp Cloud API phone numbers and templates
Users	`GET /users/me`, `PATCH /users/me`, `DELETE /users/me`	User profile
Billing	`POST /billing/checkout`, `POST /billing/portal`, `GET /billing/checkout/status`	Stripe billing (handled outside the OpenAPI spec)

Keeping the spec up to date

The API reference is generated from Go source annotations. To regenerate after changing the code:

# From core/
make docs

# Commit the updated spec (docs/ is a separate repo)
cd ../docs/
git add api-reference/openapi.json
git commit -m "docs: regenerate OpenAPI spec"

This runs swag init (generates Swagger 2.0) then swagger2openapi (converts to OpenAPI 3.0) and writes the result to docs/api-reference/openapi.json.

Inbox

Comments, DMs, and reviews across platforms.

Publishing

Create, schedule, and manage posts.

Webhooks

Get notified of events in real time.

Error Handling

All error codes and how to handle them.

Accounts

Exports

Usage

Mentions

Announcements

Billing

Brands

Events

Feedback

Inbox Comments

Inbox

Inbox Reviews

Invites

API Keys

Media

Facebook

Platforms

Instagram

LinkedIn

Threads

TikTok

WhatsApp

YouTube

Posts

Users

Webhooks

Base URL

Authentication

Request format

Response format

Endpoint groups

Keeping the spec up to date

Inbox

Publishing

Webhooks

Error Handling

​Base URL

​Authentication

​Request format

​Response format

​Endpoint groups

​Keeping the spec up to date

Inbox

Publishing

Webhooks

Error Handling

Base URL

Authentication

Request format

Response format

Endpoint groups

Keeping the spec up to date