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

# Use cases

> See how developers and AI agents use the SocialAPI REST API and MCP server for an inbox, comment-to-DM Automations, publishing, scheduling, and agents.

SocialAPI is a REST API and MCP server for the comments, direct messages (DMs), mentions, reviews, and posts of your connected social accounts. These are 5 common ways to use it, each with the guide that has the details.

## Read and answer an inbox

Read the comments, DMs, mentions, and reviews of every connected account through one set of endpoints, and answer them. Each area has its own guide: [Comments](https://docs.social-api.ai/guides/comments.md), [Direct messages](https://docs.social-api.ai/guides/direct-messages.md), [Reviews](https://docs.social-api.ai/guides/reviews.md), and [Mentions](https://docs.social-api.ai/guides/mentions.md).

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

Start with [Unified inbox](https://docs.social-api.ai/guides/inbox.md). Receive new items as they arrive with [Webhooks](https://docs.social-api.ai/guides/webhooks.md).

## Answer comments and DMs automatically

An Automation answers Instagram and Facebook comments and DMs that match keywords: a private reply with a link, a public reply, a hidden comment, or a button menu. SocialAPI runs it, so you run no server. On Instagram, a Follow gate sends the link only to people who follow the account.

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/automations \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "name": "Send the link",
    "trigger": "comment",
    "steps": [{
      "key": "start",
      "filters": [{ "type": "keyword", "keyword": { "keywords": ["link"], "match": "contains" } }],
      "actions": [{ "type": "private_reply", "private_reply": { "texts": ["Here is the link: https://example.com"] } }]
    }]
  }'
```

See [Automations](https://docs.social-api.ai/guides/automations.md).

## Publish to many platforms

Send one post to 1 or more connected accounts with one request, and read the status of each platform's copy. Add media with [Media](https://docs.social-api.ai/guides/media.md). Required fields differ per platform: Instagram, for example, needs an image or video ([Instagram publishing](https://docs.social-api.ai/platforms/instagram/publishing.md)).

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from SocialAPI!",
    "media": [{ "source_type": "url", "source": "https://cdn.example.com/launch.jpg" }],
    "platform_data": { "instagram": { "content_type": "feed" } },
    "publish_now": true,
    "targets": [
      { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" },
      { "account_id": "acc_01HZ9X4T6B8C2D5F7G9H1J3K" }
    ]
  }'
```

See [Publishing](https://docs.social-api.ai/guides/publishing.md) and [Track post delivery](https://docs.social-api.ai/guides/delivery.md).

## Schedule posts

Set `scheduled_at` instead of `publish_now` to publish at a time you choose. Edit, reschedule, or cancel the post before that time.

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Our spring sale starts today.",
    "media": [{ "source_type": "url", "source": "https://cdn.example.com/launch.jpg" }],
    "platform_data": { "instagram": { "content_type": "feed" } },
    "scheduled_at": "2026-10-20T09:00:00Z",
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }]
  }'
```

See [Scheduling](https://docs.social-api.ai/guides/scheduling.md).

## Give an AI agent access

The MCP server gives an agent in Claude, ChatGPT, or Cursor tools to read the inbox, reply, publish, and manage Automations and accounts. The operations listed under [What tools do not cover](https://docs.social-api.ai/integrations/tools.md#what-tools-do-not-cover) are REST only. Give an agent a [scoped API key](https://docs.social-api.ai/guides/scoped-keys.md) to limit what it can do.

See [MCP server](https://docs.social-api.ai/integrations/overview.md) and [MCP tools reference](https://docs.social-api.ai/integrations/tools.md).

## Related

* [Quickstart](https://docs.social-api.ai/quickstart.md) to connect an account and make your first calls
* [Core concepts](https://docs.social-api.ai/guides/concepts.md) for the objects behind these use cases
* [Supported platforms](https://docs.social-api.ai/platforms/overview.md) for what each platform allows
* [Plans and usage](https://docs.social-api.ai/guides/plans.md) for what each request costs


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