Social media API

A social media API is an HTTP interface that lets code create posts, upload media or read data on a social network. The phrase covers two different products, and search results mix them up.

Posting APIs act for an account that has granted permission: they publish, schedule and delete. Data APIs read public profiles and posts, often by scraping, and sell the results per request. This page is about posting. If you need follower counts or competitor posts, a data API is the tool, and we don't sell one.

Posting APIs come in two shapes. First-party APIs belong to the network: the X API, LinkedIn's Posts API, Bluesky's AT Protocol, Meta's Instagram Graph API, TikTok's Content Posting API. Unified APIs (us, Ayrshare, Postiz's public API and others) sit in front of several first-party APIs and give you one request format for all of them.

One POST /v1/posts checks the post against every target network's limits, publishes to each account in parallel, reads the post back where the network allows it, and returns one receipt. You send text, optional media URLs and a list of account ids.

The checks run before anything leaves our servers: length (weighted for X, graphemes for Bluesky), image count, empty posts, the same text on the same account in the last 24 hours, and per-account fair-use caps. They are plain code with no AI calls, so a dry_run: true request costs nothing and posts nothing.

Send an Idempotency-Key header. If your request times out and you retry with the same key and body, you get the original post back with Idempotent-Replayed: true instead of a second post. The same key with a different body returns 409 idempotency_key_reused.

curl https://socialsforai.com/v1/posts \
  -H "Authorization: Bearer $SOCIALS_API_KEY" \
  -H "Idempotency-Key: launch-0412" \
  -d '{
    "accounts": ["acc_bluesky", "acc_linkedin", "acc_x"],
    "text": "We just shipped webhooks.",
    "wait": true
  }'

Every post has one target per account, and each target carries its own status, URL, attempt count and error. The post's overall status is published, partially_published, failed, scheduled, publishing or canceled, derived from its targets.

In the response below, Bluesky published and was verified by reading the post back. LinkedIn failed because its 60-day token expired; the error says so and says what to do. With wait: true the call returns after delivery; without it you get 201 straight away and a post.published, post.partially_published or post.failed webhook later.

HTTP/1.1 201 Created   (trimmed: media, metadata, target ids and some target fields omitted)

{
  "id": "post_9fQ2mXc4LpZr8TwA",
  "object": "post",
  "status": "partially_published",
  "text": "We just shipped webhooks.",
  "scheduled_at": null,
  "created_at": "2026-11-01T15:04:05.000Z",
  "completed_at": "2026-11-01T15:04:07.000Z",
  "targets": [
    {
      "account_id": "acc_bluesky",
      "platform": "bluesky",
      "status": "published",
      "url": "https://bsky.app/profile/acme.bsky.social/post/3m4xq7k2c2s2a",
      "attempts": 1,
      "verified": true,
      "error": null
    },
    {
      "account_id": "acc_linkedin",
      "platform": "linkedin",
      "status": "failed",
      "url": null,
      "attempts": 1,
      "verified": false,
      "error": {
        "code": "account_needs_reauth",
        "message": "LinkedIn access token expired (they last 60 days).",
        "fix": "Reconnect the LinkedIn account with a new connect link.",
        "retryable": false
      }
    }
  ]
}

Errors that we can predict come back before publishing as a 422 preflight_failed, listing every issue with the account, the field and a fix sentence. Nothing is published when any account fails preflight, so you never get half a launch because one network's text was too long.

Errors from the network itself land on the target. Retryable ones (platform_rate_limited, platform_unavailable, media_fetch_failed on a 5xx) retry after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours, six attempts in all, then the target becomes failed. Permanent ones stop at once.

• text_too_long: shorten it, or set platform_options.x.text (or .bluesky, .linkedin) to a per-network version.
• too_many_media: X and Bluesky take 4 images, LinkedIn 20.
• duplicate_content: same text, same account, last 24 hours. Vary it or wait.
• daily_cap_reached: schedule it with scheduled_at instead.
• account_needs_reauth: send the owner a new connect link; an account.needs_reauth webhook fires when this happens.
• video_not_supported: video isn't built on any network yet.
• plan_limit_active_accounts and plan_limit_posts: Free plan limits (3 active accounts, 100 posts a month).

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "preflight_failed",
    "message": "The post would fail on 1 check(s). Nothing was published.",
    "fix": "Fix the issues below, or send dry_run: true to iterate without publishing.",
    "issues": [
      {
        "account_id": "acc_x",
        "platform": "x",
        "severity": "error",
        "code": "text_too_long",
        "field": "platform_options.x.text",
        "message": "Text is 312 characters; X allows 280.",
        "fix": "Shorten it by 32+ characters, or set platform_options.x.text to a shorter version."
      }
    ]
  }
}

Use the network's own API when you post to one network, from accounts you control, and need features a unified layer doesn't expose. That is a real and common case, and the first-party route is cheaper and has fewer moving parts.

Use a unified API when you post to two or more networks, or post for other people. Posting for other people is where first-party work grows: each network wants its own developer app, its own review (LinkedIn's Community Management API, Meta's App Review, TikTok's audit) and its own token refresh rules.

• Go first-party for one Bluesky bot. The AT Protocol has no app review and no fee; our Bluesky API guide shows the raw calls.
• Go first-party for LinkedIn Company Pages, X polls or quote posts, video, analytics, DMs or reading timelines. We don't do those yet.
• Go unified when an AI agent posts. Structured code and fix fields, idempotency keys and an MCP server save you writing that layer.
• Go unified when end users connect their own accounts and you don't want to hold their tokens or build reconnect flows.

The account owner opens a hosted connect link: OAuth for X and LinkedIn, an app password for Bluesky, the server URL and an access token for Mastodon, and a bot token plus channel or group for Telegram. You never see their password, and stored credentials are encrypted with AES-256-GCM and deleted on disconnect.

Tag the link with external_ref (your client id or user id) and every account it creates carries it. Links expire after 7 days by default, configurable from 5 minutes to 30 days. Set redirect_url and the owner lands back in your app with account_id, platform and status=connected in the query string.

curl https://socialsforai.com/v1/connect-links \
  -H "Authorization: Bearer $SOCIALS_API_KEY" \
  -d '{
    "platforms": ["bluesky", "linkedin"],
    "external_ref": "client_42",
    "redirect_url": "https://yourapp.example/connected"
  }'

# 201 → { "id": "cl_...", "object": "connect_link", "url": "...", "expires_at": "..." }

First-party posting is cheap or free in money: Bluesky charges nothing, LinkedIn publishes no per-call price, and X charges $0.015 per post and $0.200 per post with a link. The cost is engineering and review time. See X API pricing and LinkedIn API pricing for the detail.

We charge per active account, meaning one that published that month. Free covers 3 active accounts and 100 posts a month; Hobby is $9 for 5; Pro is $29 for 25; Growth is $79 for 100. Posts are unlimited on paid plans and X's fees pass through at cost. Paid billing isn't switched on yet, so every workspace starts on Free. Full table on pricing.

Other unified APIs price differently: Ayrshare starts at $149 a month for one profile, Postiz at $29 for 5 channels (read on their pricing pages). The comparisons are at vs Ayrshare and vs Postiz.

Yes. The same operations are exposed as an MCP server over Streamable HTTP at /api/mcp, with tools for listing platforms and accounts, creating connect links, creating, reading and canceling posts, and checking usage. create_post waits for delivery by default so the agent sees the result in the same turn.

An agent can even get its own key: POST /v1/workspaces returns a Free-plan API key without a browser. Setup for Claude Code is one command.

claude mcp add --transport http socials https://socialsforai.com/api/mcp \
  --header "Authorization: Bearer $SOCIALS_API_KEY"