> ## Documentation Index > Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer . > Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs. > A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits). > Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page. > Treat every ID as an opaque string: do not parse it or assume a format. > Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. # Core concepts > Learn the five objects of the SocialAPI REST API (brand, account, post, interaction, capability) and how they relate before you build. SocialAPI is a REST API and MCP server that reads and answers comments, direct messages (DMs), mentions, and reviews on connected social accounts, and publishes posts to them. Five objects shape every endpoint: brand, account, post, interaction, and capability. A brand groups accounts. An account is one connected social account. You publish a post to one or more accounts. Interactions arrive on an account. Capabilities tell you which actions a platform allows on an interaction. ## Brand A brand is the top-level group of connected accounts: one business, client, or location. Every account belongs to exactly 1 brand. Every interaction belongs to the account that received it. A post goes to 1 or more accounts as `targets[]`. ```json theme={null} { "id": "1c9f6f0e-2b3a-4c5d-8e7f-0a1b2c3d4e5f", "name": "Acme Corp", "created_at": "2026-04-12T09:30:00Z" } ``` * **A new SocialAPI account starts with 1 brand** named "Default". Rename or delete it like any other brand. * **Your plan sets how many brands you can create.** Pricing pages call a brand a profile. See [Plans and usage](https://docs.social-api.ai/guides/plans.md), and read your current count with `GET /v1/usage` ([Check your usage](https://docs.social-api.ai/guides/plans.md#check-your-usage)). * **A brand-restricted API key sees only its brands.** Use brands to keep agency clients apart. See [Brand restrictions](https://docs.social-api.ai/guides/scoped-keys.md#brand-restrictions). * **Creating a brand is not idempotent.** Brand names are not unique, so a retried `POST /v1/brands` creates a duplicate. See [Create requests are not idempotent](https://docs.social-api.ai/guides/ids.md#create-requests-are-not-idempotent). ## Account An account is one connected social account: an Instagram account, a Facebook login with its Pages, a YouTube channel, or a Google Business Profile location. Its ID starts with `acc_`, and you pass it to every endpoint that acts on the account. ```json theme={null} { "id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "platform": "instagram", "name": "Acme Corp", "username": "acmecorp", "brand_id": "1c9f6f0e-2b3a-4c5d-8e7f-0a1b2c3d4e5f", "status": "active", "permissions": null, "effective_permissions": ["posts.read", "posts.write", "comments.read", "comments.write", "messages.read", "messages.write", "analytics.read"] } ``` You connect an account with `POST /v1/accounts/connect` and send the person through the platform's consent screen. SocialAPI's own app connects most platforms, so you register nothing. X, Telegram, and Bluesky use your own app or credentials. See [Connect accounts](https://docs.social-api.ai/guides/connect-accounts.md) and [Platform apps](https://docs.social-api.ai/guides/platform-credentials.md). An account's `status` is `active`, `reconnect_recommended`, or `token_expired`. Reconnecting keeps the account's ID. See [Account status](https://docs.social-api.ai/guides/connect-accounts.md#account-status). An account's `permissions` limit what it can do on its platform. `null` means every permission, and `effective_permissions` lists the ones the account can use now. See [Account permissions](https://docs.social-api.ai/guides/permissions.md). ## Post A post is one piece of outbound content. One `POST /v1/posts` call can send it to 1 or more accounts. Each account it goes to is a target in `targets[]`, with its own status, `platform_post_id`, `permalink`, error, and metrics. That split lets one post report "published on Instagram, failed on Facebook". ```json theme={null} { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "text": "Spring collection is live.", "status": "published", "targets": [ { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "platform": "instagram", "status": "published", "platform_post_id": "17895695668004550", "permalink": "https://www.instagram.com/p/ABC123/", "metrics": { "likes": 42, "comments": 5, "shares": 0, "saves": 0 } } ], "created_at": "2026-10-13T11:00:00Z" } ``` * **A request publishes only with `publish_now` or `scheduled_at`.** With neither, `POST /v1/posts` saves a draft. * **A post is `draft`, `scheduled`, `publishing`, `published`, `partial`, `failed`, or `cancelled`.** A target is `pending`, `publishing`, `published`, `failed`, or `unpublished`. See [Post status](https://docs.social-api.ai/guides/delivery.md#post-status). * **An HTTP success means SocialAPI accepted the post.** Delivery to each platform finishes afterwards: read the post again or wait for a `post.*` webhook event. See [Track post delivery](https://docs.social-api.ai/guides/delivery.md). * **Metric names are the same on every platform.** Where a platform reports a count, it uses the keys `likes`, `comments`, `shares`, and `saves`. A key the platform does not report is `0`. A Google Business Profile target has no `metrics` object, or one whose four keys are all `0`. LinkedIn and Pinterest targets return `501 resource.not_supported`. Instagram, TikTok, YouTube, and Zalo add keys such as `views`: see [Analytics](https://docs.social-api.ai/guides/analytics.md#read-live-post-metrics). ## Interaction An interaction is anything inbound on an account: a comment on one of your posts, a DM, a mention, or a review. You read interactions with the [inbox endpoints](https://docs.social-api.ai/guides/inbox.md), and SocialAPI also sends them to your server as [webhook events](https://docs.social-api.ai/guides/webhook-events.md). Comments, reviews, DMs, and mentions have different IDs and different item shapes: | Interaction | ID prefix | Guide | | - | - | - | | Comment | `sapi_cmt_` | [Comments](https://docs.social-api.ai/guides/comments.md) | | DM | `sapi_dm_` | [Direct messages](https://docs.social-api.ai/guides/direct-messages.md) | | Review | `sapi_rev_` | [Reviews](https://docs.social-api.ai/guides/reviews.md) | | Mention | `sapi_mnt_` | [Mentions](https://docs.social-api.ai/guides/mentions.md) | Treat every ID as an opaque string. See [IDs](https://docs.social-api.ai/guides/ids.md). A comment returned by the REST API is a flat object: ```json theme={null} { "id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I", "platform_id": "17858893269577012", "platform": "instagram", "text": "Love this product!", "author_id": "17841400008460056", "author_name": "Jane Smith", "author_username": "janesmith", "is_owner": false, "is_hidden": false, "parent_id": null, "created_at": "2026-10-13T14:30:00Z", "capabilities": { "can_reply": true, "can_delete": true, "can_hide": true, "can_like": false, "can_private_reply": true } } ``` The same comment in a `comment.received` webhook event is nested: `author` holds the person and `content` holds the text. Webhook events and the mentions list share that nested shape. See [Interaction payload](https://docs.social-api.ai/guides/webhook-events.md#interaction-payload). ## Capability A capability is what one platform lets you do with one kind of feature: reply to a comment, hide it, like it, send a private reply, send a DM, reply to a review. Platforms differ, so SocialAPI reports capabilities instead of making you branch on platform names. Each comment carries a `capabilities` object with `can_reply`, `can_delete`, `can_hide`, `can_like`, and `can_private_reply`. Read it before you show a button or call an action. An action the platform does not support returns `501` with `error.code: "resource.not_supported"`. Retrying does not change that answer. For the whole picture, [Supported platforms](https://docs.social-api.ai/platforms/overview.md) compares every platform, and each platform page lists its own Capabilities table. ## Related * [Quickstart](https://docs.social-api.ai/quickstart.md) to use all five objects in one walkthrough * [Connect accounts](https://docs.social-api.ai/guides/connect-accounts.md) to create accounts and read their status * [Unified inbox](https://docs.social-api.ai/guides/inbox.md) to read and answer interactions * [Publishing](https://docs.social-api.ai/guides/publishing.md) to send posts to accounts * [IDs](https://docs.social-api.ai/guides/ids.md) for the ID format of every object * [Supported platforms](https://docs.social-api.ai/platforms/overview.md) for what each platform allows This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.