> ## 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. > ## Agent Instructions > Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer . > Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs. > A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits). > Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page. > Treat every ID as an opaque string: do not parse it or assume a format. > Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. # Connect a social account > Initiates account connection. For OAuth2 platforms returns an auth_url to redirect the user to. For apikey/credentials platforms stores the credentials immediately and returns account_id. For WhatsApp, open auth_url to run Meta's signup. When the WhatsApp Business account holds several numbers, the redirect to your redirect_uri carries status=selection_required and a connection_id: list the numbers with GET /v1/accounts/pending/{connection_id} and pick one with POST /v1/accounts/pending/{connection_id}/select. Set the top-level redirect_uri field when connecting WhatsApp so the result reaches a page you control. ## OpenAPI ````yaml /api-reference/openapi.json post /accounts/connect openapi: 3.0.0 info: description: >- Unified social media inbox API. Read and respond to comments, DMs, reviews, and mentions across Instagram, Facebook, Threads, Google Business Profile, TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and Trustpilot coming soon. title: SocialAPI.AI contact: name: SocialAPI.AI Support email: support@social-api.ai license: name: MIT version: '1.0' servers: - url: https://api.social-api.ai/v1 security: [] paths: /accounts/connect: post: tags: - Accounts summary: Connect a social account description: >- Initiates account connection. For OAuth2 platforms returns an auth_url to redirect the user to. For apikey/credentials platforms stores the credentials immediately and returns account_id. For WhatsApp, open auth_url to run Meta's signup. When the WhatsApp Business account holds several numbers, the redirect to your redirect_uri carries status=selection_required and a connection_id: list the numbers with GET /v1/accounts/pending/{connection_id} and pick one with POST /v1/accounts/pending/{connection_id}/select. Set the top-level redirect_uri field when connecting WhatsApp so the result reaches a page you control. requestBody: content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ConnectRequest' description: Platform and metadata required: true responses: '201': description: Account connected (direct auth) content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ConnectAccountResponse' '202': description: OAuth2 flow initiated content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ConnectOAuthResponse' '400': description: >- Missing platform, unsupported platform, or invalid permissions (validation.permissions_empty, validation.permission_unknown) content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '403': description: >- Plan limit reached (billing.platform_not_available or billing.brands_limit) content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' security: - BearerAuth: [] components: schemas: api_endpoints.ConnectRequest: type: object properties: brand_id: description: >- BrandID optionally specifies which brand to attach the account to. If omitted, a new brand is auto-created. type: string example: b_01HZ9X3Q4R5M6N7P8V2K0W1J metadata: description: >- Metadata contains platform-specific connection data. For tiktok, connection_type "creator" connects through TikTok's Content Posting API instead of the default Business API ("business"). type: object additionalProperties: {} onboarding: description: >- Onboarding applies to WhatsApp only. cloud_api (default) connects the number for use through the API alone. business_app connects a number that stays in use on the WhatsApp Business app, and imports its recent chats. type: string enum: - cloud_api - business_app example: cloud_api permissions: description: >- Permissions are the permissions to request for this account. If omitted, the brand's existing selection for this platform applies, and a brand with none gets every permission. Valid values: posts.read, posts.write, comments.read, comments.write, messages.read, messages.write, reviews.read, reviews.write, analytics.read. type: array items: type: string example: - comments.read - comments.write platform: description: >- Platform identifies the social platform to connect (e.g. instagram, facebook, google, threads, tiktok, linkedin). type: string example: instagram redirect_uri: description: >- RedirectURI is the customer's URL to redirect the user to after OAuth completes. If you have registered redirect URIs in the dashboard, the value must match one of them. If you have none registered, any valid https URI is accepted. If omitted, the default HTML success page is shown. type: string example: https://app.acme.com/oauth/done state: description: >- CustomerState is an opaque value echoed back to the customer's redirect URI. Max 512 chars. type: string example: session_abc123 api_endpoints.ConnectAccountResponse: type: object properties: account_id: type: string example: acc_01HZ9X3Q4R5M6N7P8V2K0W1J brand_id: description: >- BrandID is the brand the account was connected to. When the connect request named no brand, this is the brand created for it. type: string example: b7e3c1a2-4f5d-4e8a-9b1c-2d3e4f5a6b7c display_name: type: string example: Acme Corp platform: type: string example: instagram username: type: string example: acmecorp api_endpoints.ConnectOAuthResponse: type: object properties: auth_url: type: string example: https://www.instagram.com/oauth/authorize/?... message: type: string example: Redirect the user to auth_url metadata: type: object additionalProperties: {} state: type: string example: 4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2 api_endpoints.ErrorResponse: type: object properties: error: $ref: '#/components/schemas/api_endpoints.ErrorBody' request_id: description: >- RequestID matches the X-Request-ID response header. Include it when contacting support. type: string example: 01HZ9X3Q4R5M6N7P8V2K0W1J api_endpoints.ErrorBody: type: object properties: code: type: string example: resource.not_found message: type: string example: Account not found meta: type: object additionalProperties: {} securitySchemes: BearerAuth: description: >- Prefix your API key with "Bearer ". Example: `Authorization: Bearer sapi_key_...` type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.