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

# Quickstart

> Make your first social media inbox API call in under 5 minutes.

This quickstart gets you calling the SocialAPI.ai unified social media API in minutes: one key, one base URL, and the same `Interaction` schema for comments, DMs, mentions, and reviews across every connected platform.

This walks you from zero to a published post in seven steps. By the end you will have a working API key, a connected social account, a comment listed and replied to, and a post live on at least one platform. Total time: about five minutes if your social account is ready, ten if you need to create one.

## 1. Create your account

Sign up at [app.social-api.ai](https://app.social-api.ai). Verify your email and log in. Not sure which plan you need? See [plans and pricing](https://social-api.ai/pricing).

## 2. Get an API key

In the dashboard, go to **Keys**, then **New Key**. Give it a name and click **Create**.

<Warning>
  Copy the key immediately, it is shown only once. It starts with `sapi_key_`.
</Warning>

Store it in your environment:

```bash theme={null}
export SOCAPI_KEY="sapi_key_your_key_here"
```

<Tip>
  If the dashboard does not show a key after creation, refresh the Keys list. The key value itself is shown only once; if you missed it, revoke and create another.
</Tip>

## 3. Connect a social account

<Note>
  No platform developer app required. Click Connect and you're authorizing through [SocialAPI](https://social-api.ai)'s pre-approved app. Twitter is the one exception - it requires a one-time [BYOK setup](/connectors/twitter-byok). See [Platform credentials](/guides/platform-credentials) for the full story.
</Note>

In the dashboard, go to **Accounts**, then **Connect**, and choose your platform. Complete the OAuth flow in your browser.

Or connect programmatically:

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram"}'
```

The response includes an `auth_url`. Redirect the user there to complete OAuth.

<Tip>
  If `auth_url` is missing from the response, check that `platform` matches one of `instagram`, `facebook`, `threads`, `google`, `tiktok`, `linkedin`, `youtube`, `twitter`. See [OAuth flows](/guides/oauth#step-1-initiate-the-flow) for the full handshake.
</Tip>

## 4. List your accounts

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

```json theme={null}
{
  "data": [
    {
      "id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform": "instagram",
      "name": "Acme Corp",
      "username": "acmecorp"
    }
  ],
  "count": 1
}
```

Copy the `id`. You'll use it to scope inbox queries and publish posts.

<Tip>
  If the response is empty, the OAuth flow did not complete. Re-run step 3 and follow the redirect through to the end.
</Tip>

## 5. Read your inbox

List posts that have comments:

```bash theme={null}
curl "https://api.social-api.ai/v1/inbox/comments?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&limit=5" \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Then fetch comments on a specific post:

```bash theme={null}
curl "https://api.social-api.ai/v1/inbox/comments/POST_ID?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&limit=5" \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

```json theme={null}
{
  "data": [
    {
      "platform_id": "17858893269577012",
      "platform": "instagram",
      "text": "Love this product!",
      "author_id": "17841405793187218",
      "author_name": "Jane Smith",
      "author_username": "janesmith",
      "author_picture": "https://example.com/avatar.jpg",
      "is_owner": false,
      "like_count": 3,
      "reply_count": 0,
      "has_replies": false,
      "is_hidden": false,
      "parent_id": null,
      "created_at": "2026-04-15T14:30:00Z",
      "capabilities": {
        "can_reply": true,
        "can_delete": true,
        "can_hide": true,
        "can_like": true,
        "can_private_reply": true
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": ""
  }
}
```

<Tip>
  To reply to a specific comment in step 6, use the `platform_id` value above (or pass a `sapi_cmt_...` interaction ID, both are accepted).
</Tip>

<Tip>
  If `data` is empty, the account has no comments yet, or the post being queried has none. Try a different `account_id`, or post a comment from another account first.
</Tip>

## 6. Reply to a comment

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

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

<Tip>
  If you receive `501 not_supported`, the platform does not allow programmatic reply for that interaction type. Check `capabilities.can_reply` on the comment first.
</Tip>

## 7. Publish a post

Create a post and publish it to one or more platforms:

```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 world from SocialAPI!",
    "publish_now": true,
    "targets": [
      { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }
    ]
  }'
```

```json theme={null}
{
  "id": "p_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "text": "Hello world from SocialAPI!",
  "status": "publishing",
  "hidden": false,
  "retry_count": 0,
  "created_at": "2026-04-15T12:00:00Z",
  "updated_at": "2026-04-15T12:00:00Z",
  "targets": [
    {
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform": "instagram",
      "status": "publishing"
    }
  ]
}
```

The platform for each target is inferred from `account_id`, no `platform` field is required. Set `scheduled_at` instead of `publish_now` to queue the post for later. Omit both to save as a draft.

<Note>
  Omitting `scheduled_at` does **not** publish immediately, you must pass `"publish_now": true`. A post created without `publish_now` or `scheduled_at` is saved as a draft (drafts are free, no post credit is charged). To publish an existing draft later, call `POST /v1/posts/{pid}/publish`.
</Note>

### Publish a post with an image

Text-only posts need just the call above. To attach an image, upload it first, verify it, then pass its ID in `media_ids` (a flat array of strings). This is a four-step flow:

```bash theme={null}
# 1. Request a signed upload URL (media_type and filename are required)
curl "https://api.social-api.ai/v1/media/upload-url?media_type=image/jpeg&filename=launch.jpg" \
  -H "Authorization: Bearer $SOCAPI_KEY"
# -> { "media_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "upload_url": "https://...", "expires_at": "..." }

# 2. Upload the bytes to the signed URL (Content-Type must match media_type)
curl -X PUT "https://...signed-upload-url..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @launch.jpg

# 3. Verify the upload (required: flips the media from pending to ready)
curl -X POST https://api.social-api.ai/v1/media/f47ac10b-58cc-4372-a567-0e02b2c3d479/verify \
  -H "Authorization: Bearer $SOCAPI_KEY"

# 4. Create the post, referencing the media by ID
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Our spring collection is live.",
    "publish_now": true,
    "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
    "targets": [ { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" } ]
  }'
```

The field is `media_ids`, a flat array of ID strings. A raw image URL, or a different shape such as `media: [{ "media_id": "..." }]`, is not applied, and the post publishes without the image. Skipping step 3 leaves the media `pending`, and the publish fails rather than posting without it. See [Media uploads](/guides/media) for videos, carousels, and the server-side upload path.

<Tip>
  Publishing to several targets can partly succeed. A `201` means the post was created (delivery runs in the background); `207` means some targets published and others failed; `422` means all failed. When a target fails, the reason is under `targets[].error`. Do not treat `207` as a total failure. See [Publishing behavior and reliability](/guides/reliability#response-codes).
</Tip>

## What you just built

You now have a working integration: an API key authenticated through [SocialAPI](https://social-api.ai), a connected social account whose tokens we manage for you, the ability to read and respond to comments, and the ability to publish posts. Everything else in the docs builds on these primitives.

If you want to understand the data model behind what you just used, read [Core concepts](/guides/concepts). It explains the five nouns the API exposes (Brand, which pricing calls a social profile, plus Account, Post, Interaction, and Capability) in about five minutes.

## Where to go next

<CardGroup cols={2}>
  <Card title="Core concepts" icon="diagram-project" href="/guides/concepts">
    Brand, Account, Post, Interaction, Capability.
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    API keys, JWTs, and OAuth tokens.
  </Card>

  <Card title="Publishing" icon="paper-plane" href="/posts/overview">
    Per-platform fields, media constraints, scheduling.
  </Card>

  <Card title="Pagination" icon="list" href="/guides/pagination">
    Page through large result sets with cursors.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/guides/webhooks">
    Get notified of new comments, messages, and events.
  </Card>

  <Card title="Platform support" icon="grid-2" href="/guides/platforms">
    Capabilities by platform.
  </Card>
</CardGroup>