API reference - SocialAPI

The SocialAPI REST API reads and writes your connected accounts’ comments, direct messages (DMs), reviews, mentions, posts, and analytics over HTTPS with JSON. This page covers what every endpoint shares. The endpoint pages in the reference below list each operation’s parameters, request body, and responses.

Base URL

Every endpoint lives under one base URL:

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

Authentication

Every request carries a token on the Authorization header. SocialAPI accepts two token types: an API key (sapi_key_...) that you create and keep on your server, and an OAuth 2.1 access token that an app receives after a SocialAPI user approves it. A scoped API key limits a key to some scopes and brands.

curl https://api.social-api.ai/v1/accounts \
  -H "Authorization: Bearer $SOCAPI_KEY"

See Authentication to create and rotate keys, and OAuth for MCP clients for the OAuth flow.

Request format

Send a JSON body with Content-Type: application/json. Two endpoints take a multipart form instead: POST /v1/media/upload and POST /v1/posts/import.
Write every timestamp in ISO 8601 UTC, for example 2026-10-02T09:00:00Z.
Send X-Request-ID to set your own request ID: see Debugging.

Response format

A successful response is JSON with an HTTP 2xx status. List endpoints return a page of results and a cursor: see Pagination. Every object has an id that you store and send back unchanged: see IDs. A failed request to /v1 returns a non-2xx status and this body:

{
  "error": {
    "code": "validation.field_required",
    "message": "Required field is missing: platform",
    "meta": { "field": "platform" }
  },
  "request_id": "a1b2c3d4"
}

Branch on error.code, never on error.message. request_id equals the X-Request-ID response header: quote it when you report a failed request. Errors lists every code with its HTTP status, and Debugging explains request_id.

Endpoint groups

Endpoint pages cover these areas:

Group	What it covers
Accounts	Connect, list, reconnect, and disconnect accounts, and manage Pages and locations
Brands and Invites	Group accounts by brand and invite clients to connect theirs
Inbox	Comments, DMs, and reviews across platforms
Mentions	Mentions of a connected account
Automations	Rules that reply to Instagram and Facebook comments and DMs
Posts	Publish, schedule, update, retry, and delete posts, and read post metrics
Media	Upload and manage media files
Analytics and Exports	Stored account, brand, and post history, and exports
Webhooks	Webhook endpoints and their deliveries
Events, Usage, and Announcements	The events log, plan usage, and product announcements
Billing	The plan catalog: see Plans and usage
API Keys and Users	API keys and your SocialAPI profile
Platform groups	Endpoints under `/v1/platforms/` for one platform, such as WhatsApp, Google, Instagram, TikTok, and YouTube

Inbox

Comments, DMs, and reviews across platforms.

Publishing

Create, schedule, and manage posts.

Webhooks

Get notified of events in real time.

Errors

Every error code and how to handle it.

​Base URL

​Authentication

​Request format

​Response format

​Endpoint groups