# Socials API

> Publish to X, Bluesky, LinkedIn, Mastodon and Telegram (more coming) from code or AI agents with one API. Headless: no dashboard required. Pricing is per monthly *active* account (accounts that posted that month); posts are unlimited on paid plans.

Base URL: https://socialsforai.com
Auth: `Authorization: Bearer sk_...`
MCP server (Streamable HTTP): https://socialsforai.com/api/mcp (same bearer key)

## Quickstart

1. Get a key (agents may do this themselves):
   POST https://socialsforai.com/v1/workspaces  {"name":"My agent"}  → {"api_key":"sk_..."}
2. Ask a human to connect accounts:
   POST /v1/connect-links  {"platforms":["bluesky","x","linkedin"], "external_ref":"client-42"}  → {"url": "..."}
   Send the url to the account owner. Connected accounts appear in GET /v1/accounts.
3. Check postability without publishing:
   POST /v1/posts  {"accounts":["acc_..."], "text":"Hello", "dry_run": true}  → {"ok": true, "issues": []}
4. Publish (and wait for the result):
   POST /v1/posts  {"accounts":["acc_..."], "text":"Hello", "wait": true}
   Header `Idempotency-Key: <unique>` makes retries safe: the same key never publishes twice.

## Posts

POST /v1/posts
- accounts: string[] (required)
- text: string
- media: [{url, type?: "image"|"video", alt?}] (public URLs)
- platform_options: {"x": {"text": "shorter version"}} per-platform overrides
- scheduled_at: ISO-8601 (omit to publish now)
- dry_run: boolean (validate only)
- wait: boolean (publish synchronously and return final status)
- metadata: object (echoed back)

Post status: scheduled → publishing → published | partially_published | failed | canceled
Each target (one per account) has: status, url, external_post_id, attempts, verified, error {code, message, fix, retryable}.
Transient failures retry automatically with backoff (30s, 2m, 10m, 30m, 2h).

GET /v1/posts?status=&limit=&before=   GET /v1/posts/:id   DELETE /v1/posts/:id (cancel if not started)

## Preflight checks (returned as issues with code, message, fix)
text_too_long, too_many_media, video_not_supported, empty_post, duplicate_content (same text on same account within 24h),
daily_cap_reached (fair-use per account/day), account_needs_reauth, scheduled_in_past, plan_limit_* (Free plan only), x_link_cost (warning).

## Accounts & connect links
GET /v1/accounts?platform=&external_ref=&status=   GET /v1/accounts/:id   DELETE /v1/accounts/:id
POST /v1/connect-links {platforms?, external_ref?, redirect_url?, expires_in?}
Account status: active | needs_reauth. When needs_reauth, create a new connect link for that platform.

## Webhooks
POST /v1/webhooks {url, events: ["*"] | [...]}  → returns secret once
Events: post.published, post.partially_published, post.failed, post.canceled, account.connected, account.needs_reauth, account.disconnected
Signature header: `Socials-Signature: t=<unix>,v1=<hex>` where v1 = HMAC_SHA256(secret, "<t>.<raw body>").

## API keys
GET /v1/keys → your keys (prefix, name, last_used_at, current) · POST /v1/keys {name} → returns key once · DELETE /v1/keys/:id → revoke.
Owner email (for dashboard sign-in and key recovery): POST /v1/workspaces {name, email} or PATCH /v1/workspace {email} (only while unset). GET /v1/workspace shows it. Humans sign in at /login with an emailed one-time link.
Rotate: create new key, switch, revoke old. The last active key can't be revoked (409 last_active_key). Max 20 active keys.

## Usage & pricing
GET /v1/usage → active accounts this month, posts, estimated cost, recommended plan.
Plans: Free $0 (3 active accounts, 100 posts/mo) · Hobby $9 (5, +$2 each) · Pro $29 (25, +$1) · Growth $79 (100, +$0.75) · Scale $199 (400, +$0.40).
Every plan: all platforms, all account types (yours, clients', end users'), API, MCP, webhooks. Paid plans never block a post for billing.

## Platforms
GET /v1/platforms → limits per platform. Live: x, bluesky, linkedin (personal profiles), mastodon (any server), telegram (channels and groups via a bot).
Connect methods: X and LinkedIn use OAuth; Bluesky an app password; Mastodon the server URL plus an access token (Preferences → Development, scopes write:statuses write:media read:accounts); Telegram a bot token from @BotFather plus the channel @username or chat id (the bot must be an admin that can post).
Limits: Mastodon 500 characters (URLs count 23), 4 images. Telegram 4,096 characters, 1,024 with images, 10 images; Telegram posts return verified: false because bots can't read channel history; delivery is confirmed by Telegram's response.
Sandbox platform: connect a fake account and test failures with "[fail:retryable]", "[fail:permanent]", "[fail:auth]" in the text.

## Errors
{"error": {"code": "...", "message": "...", "fix": "...", "issues": [...]}}

## Guides, comparisons and tools

- [Pricing](https://socialsforai.com/pricing)
- [Docs](https://socialsforai.com/docs)
- [Social media API](https://socialsforai.com/social-media-api): How a social media posting API works, when a network's own API is the better pick, real request and response JSON, error codes and per-account pricing.
- [X API pricing](https://socialsforai.com/x-api-pricing): X (Twitter) API pricing from X's own docs: $0.015 per post, $0.20 with a link, $0.005 per read. Monthly cost tables, rate limits, ways to cut the bill.
- [LinkedIn API](https://socialsforai.com/linkedin-api): How the LinkedIn Posts API works: permissions, OAuth and 60-day tokens, required headers, image uploads, error codes, rate limits, and a one-call option.
- [LinkedIn API pricing](https://socialsforai.com/linkedin-api-pricing): LinkedIn API pricing explained from LinkedIn's docs: no per-call fee for posting, what needs approval, token lifetimes, rate limits, and per-account costs.
- [Bluesky API](https://socialsforai.com/bluesky-api): How to post with the Bluesky API (AT Protocol): curl examples, 300-grapheme limit, facets, link cards, images, rate limits, app passwords vs OAuth.
- [Instagram API](https://socialsforai.com/instagram-api): How Instagram's Content Publishing API works: account types, login options, App Review, the two-step container flow, media specs and the daily post limit.
- [TikTok API](https://socialsforai.com/tiktok-api): How TikTok's Content Posting API works: Direct Post vs inbox upload, the audit and private-only rule, video and photo specs, rate limits and error codes.
- [Make an X bot](https://socialsforai.com/twitter-bot): Build an X (Twitter) bot step by step: OAuth, posting code in curl, TypeScript and Python, X's per-post costs, rate limits and every error code explained.
- [Schedule LinkedIn posts](https://socialsforai.com/schedule-linkedin-posts): Schedule LinkedIn posts from code: one API call with scheduled_at, cancel anytime, webhooks on publish. Worked JSON example, token expiry and error fixes.
- [Schedule tweets](https://socialsforai.com/schedule-tweets): Schedule X posts from code or an AI agent: one call with scheduled_at, bulk scheduling, cancel anytime, idempotent retries, webhooks and error fixes.
- [Crosspost](https://socialsforai.com/crosspost): Crosspost from code or an AI agent: one call to X, Bluesky and LinkedIn, per-network text, length checks before publishing, and partial-success results.
- [X character limit](https://socialsforai.com/x-character-limit): The X character limit from X's docs: 280 weighted characters, URLs 23, emoji and CJK 2. Worked examples, edge cases, API errors and a free counter.
- [LinkedIn character limit](https://socialsforai.com/linkedin-character-limit): The LinkedIn post character limit is 3,000 characters. What counts, worked examples, what the API does with longer text, and how to shorten a post.
- [Bluesky character limit](https://socialsforai.com/bluesky-character-limit): Bluesky's character limit is 300 graphemes and 3,000 bytes. What a grapheme is, how emoji, links and CJK count, API errors, and a free counter.
- [LinkedIn MCP server](https://socialsforai.com/mcp/linkedin): Hosted LinkedIn MCP server for personal profiles. What each tool returns for LinkedIn, a worked dry-run session, the 60-day token, escaping, caps and error fixes.
- [X (Twitter) MCP server](https://socialsforai.com/mcp/x): Hosted X MCP server. What each tool returns for X, the 280 weighted-character and $0.20 link-post rules, OAuth with refresh, and X-specific error fixes.
- [Bluesky MCP server](https://socialsforai.com/mcp/bluesky): Hosted Bluesky MCP server, live today. What each tool returns for Bluesky, app-password setup, facets, a worked session, caps and Bluesky error fixes.
- [Claude Code](https://socialsforai.com/agents/claude-code): Connect Claude Code to LinkedIn, X and Bluesky with one claude mcp add command. Scopes, tool names, permission rules, example prompts and Claude Code-specific fixes.
- [Claude Desktop](https://socialsforai.com/agents/claude-desktop): Connect Claude Desktop to LinkedIn, X and Bluesky through mcp-remote. Exact config per OS, where the logs are, example prompts, approval and Claude Desktop fixes.
- [Cursor](https://socialsforai.com/agents/cursor): Add a social posting MCP server to Cursor with .cursor/mcp.json. Exact config, env-var keys, tool approval and auto-run, example prompts and Cursor-specific fixes.
- [OpenClaw](https://socialsforai.com/agents/openclaw): Let OpenClaw post to LinkedIn, X and Bluesky. Add the MCP server under mcp.servers, probe it, approve from chat, use toolFilter, and fix OpenClaw-specific errors.
- [Hermes Agent](https://socialsforai.com/agents/hermes-agent): Connect Hermes Agent to LinkedIn, X and Bluesky: mcp_servers entry in config.yaml, /reload-mcp, mcp_socials_ tool names, tool filters, prompts and Hermes fixes.
- [n8n](https://socialsforai.com/agents/n8n): Post to LinkedIn, X and Bluesky from n8n with one HTTP Request node. Exact node settings, idempotency keys that survive retries, response handling and n8n fixes.
- [Postiz](https://socialsforai.com/vs/postiz): Postiz pricing ($29 to $99/mo), API and MCP details, and a fair Postiz vs SocialsForAI comparison at 3 to 100 accounts. Read on Postiz's own site.
- [Post Bridge](https://socialsforai.com/vs/post-bridge): Post Bridge pricing ($39 and $99/mo), its API and MCP, and a fair Post Bridge vs SocialsForAI comparison at 3 to 100 accounts. Read on Post Bridge's site.
- [Zernio](https://socialsforai.com/vs/zernio): Zernio pricing ($6/$3/$1 per account), its API and MCP, and a fair Zernio vs SocialsForAI comparison: connected vs active billing. Read on Zernio's site.
- [Ayrshare](https://socialsforai.com/vs/ayrshare): Ayrshare pricing read on its site ($149 / $299 / $599), what a profile is, its API, and a fair comparison with an API-only alternative for developers.
- [Upload-Post](https://socialsforai.com/vs/upload-post): Upload-Post pricing (free, $24 to $438/mo), its API and MCP, profiles vs accounts, and a fair Upload-Post vs SocialsForAI comparison. Read on its own site.
- [Blotato](https://socialsforai.com/vs/blotato): Blotato pricing ($29 / $97 / $499), what AI credits cover, its API and MCP, and a fair comparison with a delivery-only posting API. Read on Blotato's site.
- [LinkedIn text formatter](https://socialsforai.com/tools/linkedin-text-formatter): Free LinkedIn text formatter: bold, italic, bold italic, monospace, underline and strikethrough for posts. Copy and paste, with accessibility notes.
- [LinkedIn post preview](https://socialsforai.com/tools/linkedin-post-preview): Free LinkedIn post preview: paste a draft to see what shows before "see more", count characters against the 3,000 limit, and fix your opening lines.
- [X (Twitter) character counter](https://socialsforai.com/tools/twitter-character-counter): Free Twitter / X character counter that counts like X: 280 limit, links = 23, emoji = 2, CJK = 2. Live weighted count, characters left and link cost.
- [Bluesky character counter](https://socialsforai.com/tools/bluesky-character-counter): Free Bluesky character counter: counts graphemes like Bluesky (300 limit) and UTF-8 bytes (3,000 limit), live as you type, with worked examples.