> ## 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 <your API key>.
> 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.
> 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.

# IDs

> Look up the ID format of every SocialAPI object, learn which IDs stay stable, and which create requests are not idempotent.

Every object SocialAPI returns has an `id` string. Treat every ID as an opaque string: store it as text, send it back unchanged, and never parse it or depend on its length, characters, or format. The formats below tell you how to recognize an ID, not how to read one.

## ID formats

| Object | ID format | Example |
| - | - | - |
| Connected account | `acc_` prefix | `acc_01HZ9X3Q4R5M6N7P8V2K0W1J` |
| Facebook Page or other page-level destination of an account | `sapi_page_` prefix | `sapi_page_01HZ9X3Q4R5M6N7P8V2K0W1J` |
| Pinterest board | `sapi_board_` prefix | `sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J` |
| Login (the `login_id` of a Facebook or Google connection) | `cred_` prefix | `cred_01HZ9X3Q4R5M6N7P8V2K0W1J` |
| Automation | `aut_` prefix | `aut_01HZ9X3Q4R5M6N7P8V2K0W1J` |
| Automation Firing | `afr_` prefix | `afr_01HZ9X3Q4R5M6N7P8V2K0W1J` |
| Comment | `sapi_cmt_` prefix | `sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I` |
| Review | `sapi_rev_` prefix | `sapi_rev_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I` |
| Direct message, as the `id` of a `dm.*` webhook event and in `message_id` and `message_ids` of a send response | `sapi_dm_` prefix | `sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I` |
| Mention | `sapi_mnt_` prefix | `sapi_mnt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I` |
| Message, as the `id` of an item in `GET /v1/inbox/conversations/{id}/messages` | UUID, no prefix | `7c9e6679-7425-40de-944b-e07fc1f90ae7` |
| Post, brand, invite, API key, webhook endpoint, webhook delivery, media file, conversation, event, export, announcement | UUID, no prefix | `7c9e6679-7425-40de-944b-e07fc1f90ae7` |

The `sapi_cmt_`, `sapi_rev_`, `sapi_dm_`, and `sapi_mnt_` IDs are interaction IDs: the `id` of each item returned by the comment, review, and mention endpoints, of each direct message in a webhook event, and of each message a send request returns. A message in a conversation's message list has a UUID `id` instead, and its `platform_id` is the platform's own ID. The two are different values for the same message. An API key's secret starts with `sapi_key_`, which is not an ID: the `id` of a key is a UUID, and the secret is shown once when you create the key.

Fields named `platform_id` hold the platform's own ID for the same object, such as an Instagram comment ID. They are different values from `id`.

## What each endpoint accepts

* **Connected account:** every endpoint that takes an account uses `acc_` IDs.
* **Post targets:** `page_id` and `board_id` accept the SocialAPI ID (`sapi_page_`, `sapi_board_`) or the platform's own ID.
* **Comment routes:** `:postId` takes the platform's post ID. `:commentId` and `comment_id` take a `sapi_cmt_` ID or the platform's comment ID.
* **Review routes:** `:id` takes a `sapi_rev_` ID or the platform's review ID.
* **Conversation routes:** `:id` takes the conversation `id` returned by `GET /v1/inbox/conversations`. It is a UUID, not a `sapi_dm_` ID.
* **Mention replies:** `media_id` takes a `sapi_mnt_` ID or the platform's media ID.
* **Read a post:** `GET /v1/posts/{pid}` takes the SocialAPI post ID or a platform post ID. A platform post ID that matches more than one post returns `409 ambiguous_post_id`: use the SocialAPI post ID.
* **Post metrics:** `GET /v1/posts/{pid}/metrics` takes the SocialAPI post ID or a platform post ID, with the same `409 ambiguous_post_id`.

A SocialAPI interaction ID of the wrong type returns `400 validation.id_invalid`: for example a `sapi_rev_` ID in a comment route. An interaction ID created for a different platform than the account returns `400 validation.id_platform_mismatch`.

## Use IDs in requests

List commented posts, then reply to one comment using its `id`:

```bash theme={null}
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "comment_id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I",
    "text": "Thank you!"
  }'
```

Response (HTTP 200):

```json theme={null}
{
  "success": true,
  "comment_id": "sapi_cmt_7Q2KDWZ9SFN4RAHB6GXEM3YLTPV1C5UJ"
}
```

`comment_id` in the response is the ID of your new reply. In this request, `17895695668004550` is the platform's post ID.

Hide a comment, with the same `sapi_cmt_` ID in the path:

```bash theme={null}
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550/sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I/hide" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J"}'
```

See [Comments](/guides/comments), [Reviews](/guides/reviews), and [Mentions](/guides/mentions) for every route that takes an interaction ID.

## What stays stable

* **Interaction IDs:** the same comment, review, or mention always has the same `id`, in every response and every webhook event. Store it and join on it. For a direct message, the `sapi_dm_` ID is stable but the message list does not return it. To match a listed message to a webhook event, compare `platform_id`.
* **Connected accounts:** an `acc_` ID stays the same for the life of the connection. Reconnecting the same platform account to your SocialAPI account keeps its `acc_` ID. Disconnecting an account with `DELETE /v1/accounts/{id}` deletes it, and connecting it again creates a new `acc_` ID.
* **Every other object:** an ID never changes for the life of the object.

Store IDs as text, not as a typed `uuid` column: formats differ per object type, so never assume one format across objects.

## Create requests are not idempotent

No create endpoint accepts an idempotency key. When a request times out and you repeat it, check first whether the first request succeeded.

| Request | What a repeat does |
| - | - |
| `POST /v1/brands` | Creates another brand. Brand names are not unique |
| `POST /v1/keys` | Creates another API key |
| `POST /v1/webhooks` | Creates another webhook endpoint, even for the same URL |
| `POST /v1/automations` | Creates another Automation, up to the limit of 50 Automations per account |
| `POST /v1/invites` | Returns `409 resource.conflict` while an active invite exists for the same brand and platform |
| `POST /v1/posts` | Returns `409 resource.conflict` when the same account already has a post with the same title and text that was created in the last 24 hours and is now `published`. Send `skip_duplicate_check: true` to publish the same content again. Drafts, scheduled posts, and posts still `publishing` are not compared |
| Replies and direct messages | Send another reply or message and cost another interaction credit |

After a timeout, persist the ID from the first response when you have it. Otherwise list the object (`GET /v1/brands`, `GET /v1/posts`) and look for it before you create another.

For webhook endpoints, `X-SocialAPI-Delivery` is the same value on every retry of one delivery. Use it to ignore a duplicate. See [Webhooks](/guides/webhooks).

## Related

* [Pagination](/guides/pagination): cursors are opaque strings too
* [Comments](/guides/comments): routes that take `sapi_cmt_` IDs
* [Reviews](/guides/reviews): routes that take `sapi_rev_` IDs
* [Track post delivery](/guides/delivery): post and target fields in post responses
* [Webhooks](/guides/webhooks): `X-SocialAPI-Delivery` and duplicate events


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.