# SocialAPI.ai - Full API Reference > One API to read, manage, and respond to social media interactions - comments, > DMs, reviews, and mentions - across Instagram, Facebook, Google Reviews, > TikTok, YouTube, X/Twitter, LinkedIn, and more. MCP-native for AI > agents and developers. Full API reference below. SocialAPI.ai is a unified social media inbox API for developers and AI agents. It replaces per-platform integrations with a single authenticated REST API and a native MCP (Model Context Protocol) server. One API key reads and responds to comments, DMs, reviews, and mentions across eight social and review platforms. ## What it does - Read comments, reviews, DMs, and mentions from connected social accounts - Reply to comments and reviews - Send direct messages - Moderate comments (hide, delete) - Publish and schedule posts - Receive real-time webhook events for new interactions - Use all of the above as MCP tools inside any AI agent runtime ## Supported platforms - Instagram: comments, DMs, mentions, post publishing - Facebook: comments, DMs, mentions, post publishing - Google Reviews: reviews, replies (read + respond) - TikTok: comments, post publishing - YouTube: comments, post publishing - X / Twitter: mentions, DMs, post publishing - Review platforms: reviews, replies (read + respond) - LinkedIn: comments, mentions, post publishing ## Authentication All /v1 endpoints require a Bearer token: Authorization: Bearer Two token types are accepted: 1. API key (format: sapi_key_): issued from the dashboard at https://app.social-api.ai. Pass as Bearer token. SHA-256 lookup + bcrypt verification against the api_keys table. 2. Auth service JWT (EdDSA/Ed25519): used by the dashboard frontend. Verified via JWKS endpoint. Not for external API clients. Obtain an API key at: https://app.social-api.ai ## Connecting social accounts Social accounts are connected via OAuth 2.0: 1. POST /v1/accounts/connect Body: { "platform": "instagram" } Response: { "auth_url": "https://..." } 2. Redirect the user to auth_url. 3. POST /v1/oauth/exchange Body: { "code": "...", "state": "..." } Response: array of ConnectedAccount objects ## Interaction IDs Every interaction has a prefixed ID encoding its type: - sapi_cmt_ - comment - sapi_rev_ - review - sapi_dm_ - direct message - sapi_mnt_ - mention Pass these IDs directly to reply/moderate endpoints without decoding. ## REST API Endpoints Base URL: https://api.social-api.ai ### Accounts GET /v1/accounts List all connected social accounts for the authenticated user. Response: { accounts: Account[] } POST /v1/accounts/connect Initiate OAuth connection for a platform. Body: { platform: string } Response: { auth_url: string } or { accounts: Account[] } (for API-key auth) POST /v1/oauth/exchange Complete OAuth flow after redirect. Body: { code: string, state: string } Response: { accounts: Account[] } ### Posts (publishing) GET /v1/accounts/:id/posts List published posts for a connected account. Query: cursor, limit, since, until Response: { posts: Post[], next_cursor?: string } POST /v1/posts Create and publish a post. Body: { text?: string, media_ids?: string[], scheduled_at?: string } Response: { post: Post } PATCH /v1/posts/:pid Update a post (platform support varies). Body: { text?: string } Response: { post: Post } DELETE /v1/posts/:pid Delete a post. Response: 204 No Content POST /v1/posts/:pid/retry Retry a failed post. Response: { post: Post } GET /v1/media/upload-url Get a presigned URL to upload media before publishing. Query: filename, content_type Response: { upload_url: string, media_id: string } POST /v1/media/:id/verify Verify a media upload completed successfully. Response: { media: Media } ### Comments GET /v1/accounts/:id/posts/:pid/comments List comments on a post. Query: cursor, limit, since, until Response: { comments: Interaction[], next_cursor?: string } GET /v1/accounts/:id/interactions/:iid/replies List replies to a comment. Query: cursor, limit Response: { replies: Interaction[], next_cursor?: string } POST /v1/accounts/:id/posts/:pid/comments/toggle Enable or disable comments on a post. Body: { enabled: boolean } Response: 200 OK ### Interactions (reply, moderate) POST /v1/accounts/:id/interactions/:iid/reply Reply to any interaction (comment, review, mention). Body: { text: string } Response: { reply: Reply } POST /v1/accounts/:id/interactions/:iid/moderate Moderate a comment (hide or delete). Body: { action: "hide" | "unhide" | "delete" } Response: 200 OK ### DMs (direct messages) GET /v1/accounts/:id/dms List DM threads for a connected account. Query: cursor, limit Response: { threads: Interaction[], next_cursor?: string } GET /v1/accounts/:id/dms/thread Get a DM thread for a specific user. Query: user_id (required) Response: { thread_id: string } POST /v1/accounts/:id/dms/:tid/send Send a DM in a thread. Body: { text: string } Response: { message: Reply } ### Reviews GET /v1/accounts/:id/reviews List reviews for a connected account (Google Reviews and other review platforms). Query: cursor, limit, since, until Response: { reviews: Interaction[], next_cursor?: string } ### Mentions GET /v1/accounts/:id/mentions List mentions for a connected account. Query: cursor, limit, since, until Response: { mentions: Interaction[], next_cursor?: string } ### Usage and limits GET /v1/usage Current usage for the authenticated user. Response: { posts_used, posts_limit, interactions_used, interactions_limit, period_start, period_end } GET /v1/accounts/:id/limits Platform-specific rate limits for a connected account. Response: { limits: { [key: string]: number } } ### API Keys GET /v1/keys List API keys for the authenticated user POST /v1/keys Create a new API key DELETE /v1/keys/:id Revoke an API key ### Webhooks (outbound) GET /v1/webhooks List registered webhook endpoints POST /v1/webhooks Create a webhook endpoint PATCH /v1/webhooks/:id Update a webhook endpoint DELETE /v1/webhooks/:id Delete a webhook endpoint Webhook events are delivered as HTTP POST to your endpoint with a unified envelope. Supported event types: comment.created, dm.received, review.created, mention.created, post.published, post.failed. ### User account GET /v1/users/me Get authenticated user profile PATCH /v1/users/me Update user profile DELETE /v1/users/me Delete user account and all connected data ## Interaction object schema { "id": "sapi_cmt_", "platform": "instagram", "type": "comment", "platform_id": "", "author": { "id": "", "name": "Display Name", "username": "@handle", "avatar_url": "https://..." }, "text": "Comment text", "created_at": "2026-03-14T12:00:00Z", "post_id": "", "parent_id": null, "metadata": {} } ## Error handling All errors return: { "error": "", "code": "" } | HTTP Status | Error code | Meaning | |-------------|------------------------|--------------------------------------| | 400 | unsupported_platform | Platform not recognized | | 400 | missing_metadata | Required field missing | | 401 | invalid_token | API key or OAuth token invalid | | 401 | user_not_provisioned | JWT user not yet provisioned | | 404 | account_not_found | Connected account not found | | 404 | not_found | Resource not found | | 409 | account_already_linked | Account already connected | | 429 | rate_limit_exceeded | Monthly plan limit reached | | 429 | platform_rate_limit | Platform-side rate limit hit | | 501 | not_supported | Capability not supported on platform | ## Plan limits | Plan | Price | Brands | Posts/month | Interactions/month | |------------|-------------|----------|-------------|-------------------| | Free | $0/month | 2 | 10 | 50 | | Starter | $29/month | 10 | Unlimited | Unlimited | | Pro | $109/month | 50 | Unlimited | Unlimited | | Business | $349/month | 200 | Unlimited | Unlimited | | Enterprise | Custom | Unlimited| Unlimited | Unlimited | Annual billing available at 20% discount (pay for 10 months, get 12). Reading (GET requests for comments, reviews, DMs, mentions) is always free and does not count against any limit. Posts and interactions (write operations: replying, sending DMs, publishing) are unlimited on all paid plans. The Free plan has monthly limits: 10 posts and 50 interactions. When the Free plan limit is reached the API returns HTTP 429 with code "rate_limit_exceeded" until the next billing period. Response headers on post/interaction endpoints: X-Posts-Limit, X-Posts-Remaining X-Interactions-Limit, X-Interactions-Remaining ## MCP server The MCP server is available at: https://api.social-api.ai/mcp It exposes 31 typed tools covering the full API surface. Connect using any MCP-compatible host (Claude, GPT-4o, open-source agent frameworks). MCP marketplace listings: - Smithery: https://smithery.ai/servers/socialapi/socialapi - Composio, MCP.so, PulseMCP: search "SocialAPI" Authentication uses the same Bearer token as the REST API. OAuth 2.1 (PKCE) is supported for MCP client authorization flows. ## SDK support SDKs are available for: - Node.js / TypeScript - Python - Direct HTTP (curl / any HTTP client) ## Key pages - https://social-api.ai/ - Product overview and getting started - https://social-api.ai/about - About SocialAPI.ai, mission, and technical philosophy - https://social-api.ai/pricing - Plan comparison and pricing - https://social-api.ai/contact - Sales, support, and partnerships - https://docs.social-api.ai/ - Full API reference, guides, and examples - https://app.social-api.ai/ - Dashboard (sign up, connect accounts, manage API keys) ## Contact - General: hello@social-api.ai - Support: support@social-api.ai - Sales: sales@social-api.ai