> ## 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. 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.

# Request IDs

> Read the X-Request-ID header and the request_id error field to identify a SocialAPI call, send your own request ID, and report a failed call.

Every response from the SocialAPI REST API carries an `X-Request-ID` header, and every error response repeats the same value as `request_id` in its body. Log it with each call, and include it when you contact support about a failed request.

## Read the request ID

```bash theme={null}
curl -i https://api.social-api.ai/v1/accounts \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

The response headers include:

```text theme={null}
HTTP 200
X-Request-ID: 9f3c1a7e
```

SocialAPI generates the ID when you do not send one: 8 lowercase hexadecimal characters, such as `9f3c1a7e`.

An error response has the ID in the body too:

```bash theme={null}
curl -i https://api.social-api.ai/v1/accounts \
  -H "Authorization: Bearer sapi_key_invalid"
```

Response (HTTP 401):

```json theme={null}
{
  "error": {
    "code": "auth.invalid_key",
    "message": "invalid or inactive API key"
  },
  "request_id": "4d82b0c6"
}
```

The `X-Request-ID` response header has the value `4d82b0c6`, the same as `request_id`.

## Send your own request ID

Send `X-Request-ID` on the request to use your own correlation ID. SocialAPI echoes your `X-Request-ID` in the response header and in `request_id` when it matches `^[a-zA-Z0-9_-]{1,64}$`. Otherwise SocialAPI generates an 8-character lowercase hexadecimal ID.

```bash theme={null}
curl -i https://api.social-api.ai/v1/accounts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "X-Request-ID: order-4821-attempt-2"
```

Response headers:

```text theme={null}
HTTP 200
X-Request-ID: order-4821-attempt-2
```

| Rule | Value |
| - | - |
| Allowed characters | Letters `A-Z` and `a-z`, digits, hyphen, and underscore |
| Length | 1 to 64 characters |
| When the value does not match | SocialAPI ignores it, returns a generated 8-character ID instead, and does not return an error |

SocialAPI does not check that your IDs are unique. Send a different value on each request, or you cannot tell the requests apart when you report one.

## Log the request ID in your application

Log the ID of every response, not only of errors, so you can look up any call later:

```typescript theme={null}
const resp = await fetch("https://api.social-api.ai/v1/accounts", {
  headers: {
    Authorization: `Bearer ${process.env.SOCAPI_KEY}`,
    "X-Request-ID": myCorrelationId,
  },
});

const requestId = resp.headers.get("X-Request-ID");

if (!resp.ok) {
  const body = await resp.json();
  console.error("SocialAPI error", {
    code: body.error.code,
    message: body.error.message,
    request_id: body.request_id,
  });
} else {
  console.info("SocialAPI call", { request_id: requestId });
}
```

## Report a failed request

Send support the `request_id`, the HTTP method and path, and the time of the call. The `request_id` identifies the single request that failed.

Two other IDs identify different things:

* **Delivery ID:** `X-SocialAPI-Delivery` on a webhook your endpoint receives identifies one webhook delivery, not an API request. See [Webhooks](https://docs.social-api.ai/guides/webhooks.md).
* **Target errors:** a failed post target shows its reason in `targets[].error`, with no `request_id`. Report the post ID and the target's `account_id`. See [Track post delivery](https://docs.social-api.ai/guides/delivery.md).

## Related

* [Errors](https://docs.social-api.ai/guides/errors.md): the error envelope and every error code
* [Authentication](https://docs.social-api.ai/guides/authentication.md): `auth.*` errors for a missing or invalid API key
* [Rate limits](https://docs.social-api.ai/guides/rate-limits.md): handle HTTP 429 and `Retry-After`
* [Webhooks](https://docs.social-api.ai/guides/webhooks.md): `X-SocialAPI-Delivery` on webhook deliveries
* [IDs](https://docs.social-api.ai/guides/ids.md): formats of SocialAPI object IDs


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