Skip to main content

​
Base URL

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

​
Authentication

All endpoints require a Bearer token. The API accepts three token types:
Token typeFormatUse case
API keysapi_key_...External API clients
Auth service JWTEdDSA signed JWTDashboard frontend
OAuth 2.1 access tokenEdDSA signed JWTMCP / 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 statusMeaning
400Invalid request parameters
401Invalid or missing API key
403Feature not available on your plan
404Account or resource not found
409Account already linked
410Resource gone (expired invite, closed reply window)
412BYOK credentials missing
413Storage quota exceeded
429Monthly resource limit or upstream platform rate limit hit
501Platform does not support this operation

​
Endpoint groups

GroupEndpointsDescription
AccountsGET /accounts, POST /accounts/connect, DELETE /accounts/:id, GET /accounts/:id/creator-info, GET /accounts/:id/pages, PATCH /accounts/:id/pages/:pageId, GET /accounts/:id/limitsConnect, list, and disconnect social accounts; manage pages and per-account creator info
BrandsGET /brands, POST /brands, PATCH /brands/:id, DELETE /brands/:idManage workspaces (brands)
InvitesGET /invites, POST /invites, DELETE /invites/:idBrand invite tokens
Inbox - CommentsGET /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-replyList commented posts and replies, reply, moderate (hide, like, delete, private reply)
Inbox - ConversationsGET /inbox/conversations, GET /inbox/conversations/:id, PATCH /inbox/conversations/:id, GET .../messages, POST .../messages, POST .../readList conversations, read and send DMs, mark as read
Inbox - ReviewsGET /inbox/reviews, POST /inbox/reviews/:id/replyRead reviews and reply
MentionsGET /accounts/:id/mentionsRead mentions for a connected account
PublishingPOST /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/validateCreate, schedule, update, delete, retry, and monitor posts
Media LibraryGET /media, DELETE /media/:id, GET /media/storage, GET /media/upload-url, POST /media/upload, POST /media/:id/verifyUpload, list, delete media files and check storage
ExportsPOST /accounts/:id/export, GET /exports, GET /exports/:id, GET /exports/:id/videosRun and read analytics exports
EventsGET /events, GET /events/summaryUnified events log
UsageGET /usageCheck workspace plan usage
API KeysGET /keys, POST /keys, DELETE /keys/:idManage API keys
WebhooksGET /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/eventsManage outbound webhook endpoints, inspect deliveries, list event catalog
OAuth redirect URIsGET /oauth/redirect-uris, POST /oauth/redirect-uris, DELETE /oauth/redirect-uris/:idManage the OAuth redirect URI whitelist (dashboard only)
Twitter BYOKGET /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/testManage your Twitter / X developer app credentials
WhatsAppPOST /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-templateManage WhatsApp Cloud API phone numbers and templates
UsersGET /users/me, PATCH /users/me, DELETE /users/meUser profile
BillingPOST /billing/checkout, POST /billing/portal, GET /billing/checkout/statusStripe 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.