Socialapi

Initiate connecting a new social media account. For OAuth2 platforms (instagram, facebook) returns an auth_url the user must visit to authorize access. After authorization, the account is connected automatically — no follow-up call needed. Present the auth_url link to the user...

Create a new brand to group social accounts for a business, client, or project. Each brand can connect one account per platform. The number of brands is limited by your plan tier.

Create an analytics export for a connected account. Enqueues an async job that collects post data, engagement metrics, and optionally video transcripts and AI vision analysis into a downloadable Excel report and shareable report page. Subject to plan limits: exports per month,...

Create a platform invite link for a brand. The invite allows someone to connect a social media account to the brand via a one-time URL. expires_in_days must be one of: 1, 3, 7, 14, 30 (defaults to 7). Returns the invite token and shareable URL.

Generate a new API key (prefixed sapi_key_) for programmatic API access. The raw key is returned exactly once in the response and cannot be retrieved later -- store it securely immediately. All keys for a user share the same monthly quota pool. Provide a descriptive name to id...

Create or schedule a post to one or more connected social media accounts. Omit targets and scheduled_at to create a draft. Provide targets to publish; omit scheduled_at for immediate publish, or provide an RFC3339 timestamp to schedule. Attach media by first uploading via soci...

Register a new webhook endpoint to receive real-time event notifications. The URL must be HTTPS. Specify which event types to subscribe to (comment.received, dm.received, review.received, mention.received, post.published, post.failed, post.scheduled). The signing secret is ret...

Delete a brand and disconnect all its connected social accounts. This is irreversible.

Permanently delete a comment from the platform and remove it from the inbox database. This action is irreversible. Supported on Instagram, Facebook, and YouTube.

Permanently delete the authenticated user account and ALL associated data including API keys, connected social accounts, usage logs, webhook endpoints, and OAuth consents. This action is completely irreversible -- all API keys for this user stop working immediately. Confirm th...

No parameter schema in public metadata yet.

Permanently delete a media file from the media library and object storage. This is irreversible. If the media is referenced by any post, the post will lose that attachment. Use social_api_list_media to find the media_id.

Delete a published post from the social media platform, or cancel a scheduled/failed post before it is published. For published posts, this removes the post from the platform (irreversible). Provide the post_id.

Delete a business reply to a review. Requires account_id and the platform review_id. Supported on Google Business. Returns 501 for platforms that do not support deleting review replies. This action is irreversible.

Permanently delete a webhook endpoint. Future events will no longer be delivered to this URL. Any in-flight deliveries may still complete. This is irreversible. Use social_api_list_webhooks to find the webhook_id.

Disconnect a connected social media account. Removes the stored OAuth tokens and disassociates the account from the user. Any scheduled posts targeting this account will fail on publish. This is irreversible — to reconnect, use social_api_connect_account again. Use social_api_...

Get aggregated event counts for a time window. Returns total events, failure count broken down by error category, counts by event category (post, inbox, account, api, webhook), inbox breakdown (comment vs DM vs mention), and the plan's retention window in days. Use to check sy...

Complete an OAuth2 account connection by exchanging the authorization code received after the user authorized access. Requires platform, the authorization code, and metadata including redirect_uri and state (from social_api_connect_account). For Facebook, a single user token m...

Get platform-specific API usage limits and quotas for a connected account, as reported by the platform itself (e.g., Instagram daily posting limits). Returns a map of quota keys to remaining counts. Not all platforms expose usage limits -- returns 501 for Facebook and platform...

List replies to a specific comment. The interaction_id must be a comment ID starting with sapi_cmt_ (from social_api_get_comments). Returns reply interaction objects in the same format. Supports pagination via cursor and since filter. Max 100 results (default 20). Supported on...

Get platform-specific content constraints for post creation. Returns per-platform limits including max text length, max media count, supported media types, max file sizes, aspect ratio requirements, and video duration limits. Use before creating a post to validate content will...

No parameter schema in public metadata yet.

Get details for a single DM conversation including participant info, unread count, status (active/archived), and last message preview. The conversation_id comes from social_api_list_conversations.

Fetch creator-facing profile details for a connected account: display name, username, profile picture, bio, follower/following counts, and platform-specific publishing capabilities (e.g. TikTok privacy levels, duet/stitch permissions). Use this before building a post UI so def...

Get the status and result of an analytics export. Returns status (pending, processing, completed, failed), progress (total_videos, processed_videos), and for completed exports: a presigned Excel download URL (valid 15 minutes) and a shareable report page URL. Poll this after s...

Get the cached video data from a completed analytics export. Returns the full video array with per-video analytics (views, likes, comments, shares, duration, transcripts, vision analysis). The export must be in 'completed' status. Use social_api_get_export to check status first.

Get the authenticated user's profile. Returns id (UUID), email, plan tier (free, starter, pro, business, or enterprise), onboarding status (true if onboarding is incomplete), and avatar_url. Use this to check the current plan tier before performing plan-gated operations.

No parameter schema in public metadata yet.

Get a presigned S3-compatible URL for uploading a media file to attach to a post. Provide the MIME type (e.g., image/jpeg, image/png, video/mp4) and the original filename. Upload workflow: (1) call this tool to get upload_url and media_id, (2) upload the file to the upload_url...

List brand mentions and tags for a connected account -- posts by other users that mention or tag your account. Returns interaction objects with id (prefixed sapi_mnt_), author, text, media_url, and timestamp. Supported on Instagram (@mentions and tags) and Facebook (page menti...

Get full details for a single post including text, status, scheduled/published timestamps, per-platform delivery details with engagement metrics (likes, comments, shares, saves), and media IDs. Use the post_id from social_api_list_posts or social_api_create_post.

Fetch live engagement metrics for a published post from each target platform. Returns per-platform metrics including like_count, comments_count, shares_count, saves_count, impressions, reach, and platform-specific extra_metrics. Triggers a real-time refresh from platform APIs.

List reviews across connected accounts (applicable to Google Business, Trustpilot, and similar review platforms). Fan-out queries all matching accounts in parallel. Returns review interaction objects with id, reviewer name, rating, text, and timestamp. Use social_api_reply_to_...

Get storage usage and quota for the authenticated user's media library. Returns used_bytes, limit_bytes (-1 if unlimited), and file_count. Storage limits vary by plan: Free (100 MB), all paid plans (unlimited).

No parameter schema in public metadata yet.

Get resource usage for the current billing period. Returns counts and limits for brands (brand slots), posts (create_post and retry_post operations), and interactions (reply and send_dm operations), plus period_start and period_end timestamps. Use before billed operations to c...

No parameter schema in public metadata yet.

Get details for a single webhook endpoint including URL, subscribed events, is_active status, a secret hint (last 4 chars only -- the full secret is returned once at creation), and delivery stats for the last 24 hours and last 7 days (delivered vs failed counts). Use social_ap...

Get full details of a single webhook delivery attempt: request payload, response body, response headers, HTTP status code, attempt count, and any error message. Use social_api_list_webhook_deliveries to find the delivery_id. Essential for diagnosing why a delivery failed.

Hide a comment from public view on the platform. The comment remains in the database but is marked hidden. Reversible — use social_api_unhide_comment to restore. Supported on Instagram, Facebook, and Threads.

Like a comment on behalf of the connected account. Supported on Facebook and Twitter. Returns 501 for platforms without like support.

List pages (e.g. Facebook Pages) for a connected account. Returns page IDs, names, default/active status. Use the returned page IDs as the page_id parameter in publishing and inbox tools.

List all connected social media accounts for the authenticated user. Returns account details including platform name, username, connection status, and platform-specific metadata (follower_count, video_count, avatar_url, etc.). Use the returned account IDs as the account_id par...

List all brands for the authenticated user. Each brand groups social accounts for one business, client, or project. Returns brand id, name, connected accounts count, and timestamps.

No parameter schema in public metadata yet.

List inbox DM conversations for the authenticated user, sorted by most recently active. Optionally filter by connected account, platform, or status (active/archived). Returns conversation objects with id, participant name/picture, last message preview, and unread count. Suppor...

List developer events (unified activity log). Filter by category (post, webhook, inbox, api, account), status, platform, action, account, or resource. Shows publishing attempts, webhook deliveries, inbound platform events, API calls, and account lifecycle events. Sorted newest...

List the 50 most recent analytics exports for the authenticated user, newest first. Optionally filter by status (pending, processing, completed, failed). Returns export ID, account, platform, status, progress, and timestamps.

List inbox posts (posts that have received comments) for the authenticated user. Optionally filter by account, platform, minimum comment count, or updated-since timestamp. Sorted newest first by default (sort_by=date). Use social_api_list_post_comments to fetch comments for a...

List all platform invites for a brand, ordered by creation date (newest first). Returns both active and expired/used invites. Use is_active to filter in the response.

List all API keys for the authenticated user. Returns key metadata including id, name, preview (first characters of the key), is_active status, last_used_at timestamp, and created_at. The full key value is never shown after creation. Use this to audit active keys or find a key...

No parameter schema in public metadata yet.

List uploaded media files in the user's media library. Returns media objects with id, filename, content_type, size_bytes, status (pending/ready), and created_at. Use media IDs from here or from social_api_get_media_upload_url when creating posts. Supports pagination via cursor.

List messages in a DM conversation, sorted newest first. The conversation_id comes from social_api_list_conversations. Returns message objects with id, direction (incoming/outgoing), text, sender info, and timestamp. Supports pagination via cursor. Max 200 results (default 50).

List comments for a specific inbox post, sorted oldest-first. The inbox_post_id comes from social_api_list_inbox_posts. Requires the account_id that owns the post. Returns comment objects with text, author info, like_count, reply_count, is_hidden, and is_liked flags. Supports...

List all posts (drafts, scheduled, published, failed) with rich filtering. Supports filtering by status, platform, account_ids, date range, text search. Returns posts with per-platform delivery details and engagement metrics. Use cursor for pagination.

List recent delivery attempts for a webhook endpoint. Each delivery includes id, event_type, status (pending, delivered, failed), HTTP response code, attempt count, and timestamps. Filter by status or event_type. Keyset cursor pagination via the cursor field. Use this to debug...

List all registered webhook endpoints for the authenticated user. Returns endpoint details including id, url, subscribed event types, is_active status, and created_at. Available event types: comment.received, dm.received, review.received, mention.received, post.published, post...

No parameter schema in public metadata yet.

Mark all messages in a conversation as read, resetting the unread count to zero. Idempotent -- calling on an already-read conversation has no effect. Use social_api_list_conversations to find the conversation_id.

Moderate a comment by hiding, unhiding, or deleting it. The interaction_id must be a comment ID starting with sapi_cmt_. Actions: 'hide' removes from public view (reversible), 'unhide' restores a hidden comment, 'delete' permanently removes it (irreversible). Returns 501 for p...

Update the authenticated user's profile. Currently only supports marking onboarding complete by setting onboarding=false. Setting onboarding=true returns an error. Returns the updated user profile. Idempotent -- calling with onboarding=false when already false has no effect.

Send a private reply (DM) in response to a comment, visible only to the commenter. Max 1000 characters. Consumes 1 interaction credit. Supported on Instagram and Facebook. Returns 501 for platforms that do not support private replies.

Reply publicly to a post or a specific comment. Provide account_id and post_id; optionally also comment_id to target a specific comment thread. The reply appears publicly on the post. Max 2200 characters. Consumes 1 interaction credit. Returns the created reply ID.

Reply to a review as the business. The reply appears publicly as the business response. Requires account_id and the platform review_id. Max 2200 characters. Consumes 1 interaction credit. Returns the created reply ID.

Retry publishing a post that previously failed. Only posts in 'failed' or 'partial' status can be retried -- re-enqueues only the failed platform deliveries. Consumes 1 post credit.

Manually retry a failed webhook delivery. Re-sends the original payload to the endpoint URL with a fresh attempt count. Use this after fixing an endpoint that was returning errors. Use social_api_list_webhook_deliveries (filtered by status=failed) to find the delivery_id.

Revoke an active platform invite, making the invite URL immediately invalid. This is irreversible. Use social_api_list_invites to find the invite_id.

Permanently deactivate an API key. This is irreversible -- the key immediately stops working for all API requests. Use social_api_list_keys to find the key_id. Revoking an already-revoked key is a no-op (idempotent). Does not affect other active keys for the same user.

Send a direct message in an existing inbox conversation. The conversation_id comes from social_api_list_conversations. Specify the account_id to send from. Max 1000 characters. Consumes 1 interaction credit. On Facebook Messenger, messages can only be sent within 24 hours of t...

Send feedback to the SocialAPI team. Use when a user wants to report a bug, request a feature, or share general feedback. Type must be one of: 'bug', 'feature_request', or 'general'. The feedback is stored in the database and the team is notified. This is the preferred way to...

Send a test event to a webhook endpoint to verify it is reachable and correctly configured. Takes an event_type (e.g. comment.received) and a raw JSON payload. Returns the delivery result including HTTP response code and any error. Does not charge the user's event quota. Use t...

Restore a previously hidden comment to public view. Supported on Instagram, Facebook, and Threads.

Remove a like from a comment previously liked by the connected account. Supported on Facebook and Twitter. Returns 501 for platforms without like support.

Unpublish a post from one or all platforms. Removes the post from the social media platform but keeps the post record in SocialAPI. Optionally specify account_id to unpublish from a single platform only; omit to unpublish from all. This is irreversible on the platform side.

Update a page's default or active status for a connected account. Set is_default=true to make this the default page for publishing and inbox operations. Set is_active=false to deactivate a page (it will no longer receive events or appear in default listings). Idempotent -- set...

Rename a brand. Only the name can be changed; connected accounts are not affected. Idempotent -- setting the same name has no effect. Use social_api_list_brands to find the brand_id first.

Update a conversation's status. Set status to 'archived' to move it out of the active inbox, or 'active' to restore it. Idempotent -- setting the current status has no effect. Use social_api_list_conversations to find the conversation_id.

Update the content of a draft, scheduled, or failed post. Only posts in 'draft', 'scheduled', or 'failed' status can be updated. Provide the post_id. Does not consume additional credits.

Update an existing business reply to a review. Requires account_id and the platform review_id. Max 2200 characters. Supported on Google Business. Returns 501 for platforms that do not support updating review replies.

Update an existing webhook endpoint. Change the URL, subscribed event types, or enable/disable it (is_active). At least one field must be provided. Idempotent -- setting the same values has no effect. Use social_api_list_webhooks to find the webhook_id.

Validate post content against platform-specific constraints before creating a post. Checks text length, media counts, file types, aspect ratios, and other platform rules. Returns valid (bool), errors (blocking issues), and warnings (non-blocking). Provide either platforms (by...

Confirm that a media file was successfully uploaded to the presigned URL. Call this after uploading the file via HTTP PUT to the URL from social_api_get_media_upload_url. Once verified, the media_id can be included in social_api_create_post's media_ids array.