> ## 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.

# 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.



## 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.
      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 or unsupported platform
          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
          type: object
          additionalProperties: {}
        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
        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'
    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

````