Quickstart

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

2. Get an API key

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

Copy the key immediately, it is shown only once. It starts with sapi_key_.

Store it in your environment:

export SOCAPI_KEY="sapi_key_your_key_here"

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.

No platform developer app required. Click Connect and you’re authorizing through SocialAPI’s pre-approved app. Twitter is the one exception - it requires a one-time BYOK setup. See Platform credentials for the full story.

In the dashboard, go to Accounts, then Connect, and choose your platform. Complete the OAuth flow in your browser. Or connect programmatically:

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.

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 for the full handshake.

4. List your accounts

curl https://api.social-api.ai/v1/accounts \
  -H "Authorization: Bearer $SOCAPI_KEY"

{
  "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.

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

5. Read your inbox

List posts that have comments:

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:

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

{
  "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": ""
  }
}

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

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.

6. Reply to a comment

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"}'

{
  "success": true,
  "comment_id": "sapi_cmt_cmVwbHk6MTIzNDU2Nzg5"
}

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.

7. Publish a post

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

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" }
    ]
  }'

{
  "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.

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.

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:

# 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 for videos, carousels, and the server-side upload path.

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.

What you just built

You now have a working integration: an API key authenticated through SocialAPI, 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. 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

Core concepts

Brand, Account, Post, Interaction, Capability.

Authentication

API keys, JWTs, and OAuth tokens.

Publishing

Per-platform fields, media constraints, scheduling.

Pagination

Page through large result sets with cursors.

Webhooks

Get notified of new comments, messages, and events.

Platform support

Capabilities by platform.

Getting Started

Core Concepts

1. Create your account

2. Get an API key

4. List your accounts

5. Read your inbox

6. Reply to a comment

7. Publish a post

Publish a post with an image

What you just built

Where to go next

Core concepts

Authentication

Publishing

Pagination

Webhooks

Platform support

​1. Create your account

​2. Get an API key

​3. Connect a social account

​4. List your accounts

​5. Read your inbox

​6. Reply to a comment

​7. Publish a post

​Publish a post with an image

​What you just built

​Where to go next

Core concepts

Authentication

Publishing

Pagination

Webhooks

Platform support

1. Create your account

2. Get an API key

3. Connect a social account

4. List your accounts

5. Read your inbox

6. Reply to a comment

7. Publish a post

Publish a post with an image

What you just built

Where to go next