Skip to main content

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.

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. Verify your email and log in. Not sure which plan you need? See plans and pricing.

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

​
3. Connect a social account

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?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.
If status is failed, inspect targets[].error for the per-platform reason. The most common failure is missing required fields per platform: see Posts.

​
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, Account, Post, Interaction, 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.