SocialClaw Connections and Accounts API

openapi: 3.2.0
info:
  title: SocialClaw Connections and Accounts API
  version: 1.0.0
  description: Complete SocialClaw API reference for social account connections, media uploads, validation, scheduling, publishing, analytics, dashboard APIs, webhooks, and delivery URLs.
servers:
- url: https://getsocialclaw.com
  description: SocialClaw production API
security:
- BearerAuth: []
tags:
- name: Connections and Accounts
  description: Start OAuth or manual connections, inspect connected accounts, capabilities, settings, and provider discovery actions.
paths:
  /v1/connections/start:
    post:
      tags:
      - Connections and Accounts
      operationId: post_v1_connections_start
      summary: Start connection
      description: 'Starts a provider connection. OAuth providers return an authorize URL; Telegram and Discord create manual connections.


        Note: Supported providers: x, facebook, instagram_business, instagram, threads (when enabled), snapchat, tiktok, linkedin, linkedin_page, pinterest, youtube, reddit, discord, telegram, wordpress.


        Note: For Telegram, include botToken and chatId. For Discord, include webhookUrl.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionStartRequest'
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/connections:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_connections
      summary: List connections
      description: Lists OAuth and manual connection handshakes for the workspace.
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/connections/health:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_connections_health
      summary: Connections health
      description: Checks connected account health and provider readiness.
      security:
      - BearerAuth: []
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          type: string
        description: Optional provider filter.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceHealthResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/connections/{connectionId}:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_connections_connectionId
      summary: Connection status
      description: Returns the status of one connection handshake.
      security:
      - BearerAuth: []
      parameters:
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
        description: Connection id.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_accounts
      summary: List connected accounts
      description: Lists connected social accounts and destinations in the workspace.
      security:
      - BearerAuth: []
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          type: string
        description: Optional provider filter.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts/capabilities:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_accounts_capabilities
      summary: List account capabilities
      description: Lists publishing capabilities across connected accounts.
      security:
      - BearerAuth: []
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          type: string
        description: Optional provider filter.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilitiesResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts/{accountId}/capabilities:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_accounts_accountId_capabilities
      summary: Get account capabilities
      description: Returns publishing capabilities for one connected account.
      security:
      - BearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Connected account id.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilitiesResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts/{accountId}/settings:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_accounts_accountId_settings
      summary: Get publish settings
      description: Returns provider-specific settings fields for one account, such as privacy, reply controls, or media modes.
      security:
      - BearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Connected account id.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishSettingsResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts/{accountId}/actions:
    get:
      tags:
      - Connections and Accounts
      operationId: get_v1_accounts_accountId_actions
      summary: List discovery actions
      description: Lists provider discovery actions available for one connected account.
      security:
      - BearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Connected account id.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryActionsResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts/{accountId}/actions/{actionId}:
    post:
      tags:
      - Connections and Accounts
      operationId: post_v1_accounts_accountId_actions_actionId
      summary: Run discovery action
      description: Runs a provider discovery action such as syncing boards, pages, or remote channel metadata.
      security:
      - BearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Connected account id.
      - name: actionId
        in: path
        required: true
        schema:
          type: string
        description: Discovery action id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OkResponse'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResultResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/accounts/{accountId}:
    delete:
      tags:
      - Connections and Accounts
      operationId: delete_v1_accounts_accountId
      summary: Disconnect account
      description: Disconnects a social account from the workspace.
      security:
      - BearerAuth: []
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
        description: Connected account id.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /oauth/{provider}/callback:
    get:
      tags:
      - Connections and Accounts
      operationId: get_oauth_provider_callback
      summary: OAuth provider callback
      description: 'Completes provider OAuth. This route is called by providers after the user authorizes SocialClaw.


        Note: Human users are redirected back to the dashboard or mobile app.


        Note: Do not call this directly unless you are testing a provider OAuth redirect.'
      security: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
        description: Provider id.
      responses:
        '200':
          description: Successful response.
      x-socialclaw-auth: callback
      x-socialclaw-surface: callback
components:
  schemas:
    DiscoveryAction:
      type: object
      description: Provider discovery action such as syncing boards, pages, or channels.
      additionalProperties: true
      properties:
        id:
          type: string
          description: Action id.
        label:
          type: string
          description: Display label.
        description:
          type:
          - string
          - 'null'
          description: What the action does.
        provider:
          type:
          - string
          - 'null'
          enum:
          - x
          - threads
          - meta
          - facebook
          - instagram_business
          - instagram
          - snapchat
          - tiktok
          - linkedin
          - linkedin_page
          - pinterest
          - youtube
          - reddit
          - discord
          - telegram
          - wordpress
          - null
        inputSchema:
          type:
          - object
          - 'null'
          description: Optional JSON Schema for action input.
      required:
      - id
      - label
    CapabilitiesResponse:
      type: object
      description: Capability response.
      additionalProperties: false
      properties:
        ok:
          const: true
        capabilities:
          type: array
          description: Capabilities.
          items:
            $ref: '#/components/schemas/Capability'
      required:
      - ok
      - capabilities
    PublishSettingsResponse:
      type: object
      description: Publish settings response.
      additionalProperties: false
      properties:
        ok:
          const: true
        publishSettings:
          $ref: '#/components/schemas/PublishSettings'
      required:
      - ok
      - publishSettings
    ConnectionsResponse:
      type: object
      description: Connection list response.
      additionalProperties: false
      properties:
        ok:
          const: true
        connections:
          type: array
          description: Connections.
          items:
            $ref: '#/components/schemas/Connection'
      required:
      - ok
      - connections
    Capability:
      type: object
      description: Publishing capabilities for a connected account or provider.
      additionalProperties: true
      properties:
        provider:
          type: string
          enum:
          - x
          - threads
          - meta
          - facebook
          - instagram_business
          - instagram
          - snapchat
          - tiktok
          - linkedin
          - linkedin_page
          - pinterest
          - youtube
          - reddit
          - discord
          - telegram
          - wordpress
        accountId:
          type:
          - string
          - 'null'
          description: Connected account id.
        canPublish:
          type: boolean
          description: Whether SocialClaw can publish to this account.
        media:
          type:
          - object
          - 'null'
          description: Media limits and supported shapes.
        settings:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Provider settings fields.
    PublishSettings:
      type: object
      description: Provider-specific publish settings. Returned fields are authoritative for UI generation.
      additionalProperties: true
      properties:
        supported:
          type: boolean
          description: Whether settings are available for this account.
        target:
          type:
          - object
          - 'null'
          description: Provider and account type target.
        fields:
          type: array
          description: Field descriptors.
          items:
            type: object
        discovery:
          type:
          - object
          - 'null'
          description: Provider media delivery and publish-shape notes.
    ConnectedAccount:
      type: object
      description: Social account or destination connected to a SocialClaw workspace.
      additionalProperties: true
      properties:
        id:
          type: string
          description: Connected account id.
        provider:
          type: string
          enum:
          - x
          - threads
          - meta
          - facebook
          - instagram_business
          - instagram
          - snapchat
          - tiktok
          - linkedin
          - linkedin_page
          - pinterest
          - youtube
          - reddit
          - discord
          - telegram
          - wordpress
          description: Canonical provider id.
        handle:
          type: string
          description: Stable account handle used in schedules.
        displayName:
          type:
          - string
          - 'null'
          description: Display name.
        accountType:
          type:
          - string
          - 'null'
          description: Provider-specific account type.
        externalId:
          type:
          - string
          - 'null'
          description: Provider account id.
        status:
          type:
          - string
          - 'null'
          description: Connection status.
        createdAt:
          type:
          - string
          - 'null'
          description: Creation time.
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          description: Last update time.
          format: date-time
      required:
      - id
      - provider
      - handle
    OkResponse:
      type: object
      description: Generic successful response.
      additionalProperties: true
      properties:
        ok:
          const: true
          description: Always true for successful JSON API responses.
      required:
      - ok
    ConnectionStartRequest:
      type: object
      description: Request to start an OAuth or manual connection. Telegram and Discord use manual credentials; other providers return an OAuth URL.
      additionalProperties: true
      properties:
        provider:
          type: string
          enum:
          - x
          - threads
          - meta
          - facebook
          - instagram_business
          - instagram
          - snapchat
          - tiktok
          - linkedin
          - linkedin_page
          - pinterest
          - youtube
          - reddit
          - discord
          - telegram
          - wordpress
          description: Provider to connect.
        botToken:
          type:
          - string
          - 'null'
          description: Telegram bot token. Also accepted as bot_token.
        chatId:
          type:
          - string
          - 'null'
          description: Telegram chat id. Also accepted as chat_id.
        webhookUrl:
          type:
          - string
          - 'null'
          description: Discord webhook URL. Also accepted as webhook_url.
        client:
          type:
          - string
          - 'null'
          description: Optional client hint, for example ios.
        callbackScheme:
          type:
          - string
          - 'null'
          description: Optional mobile callback scheme. Also accepted as callback_scheme.
      required:
      - provider
    Connection:
      type: object
      description: Connection handshake status.
      additionalProperties: true
      properties:
        id:
          type: string
          description: Connection id.
        provider:
          type: string
          enum:
          - x
          - threads
          - meta
          - facebook
          - instagram_business
          - instagram
          - snapchat
          - tiktok
          - linkedin
          - linkedin_page
          - pinterest
          - youtube
          - reddit
          - discord
          - telegram
          - wordpress
          description: Provider being connected.
        status:
          type:
          - string
          - 'null'
          description: pending, connected, failed, or provider-specific state.
        authorizeUrl:
          type:
          - string
          - 'null'
          description: OAuth authorize URL when OAuth is required.
        account:
          anyOf:
          - $ref: '#/components/schemas/ConnectedAccount'
          - type: 'null'
        error:
          type:
          - string
          - 'null'
          description: Connection error message, when failed.
        createdAt:
          type:
          - string
          - 'null'
          description: Creation time.
          format: date-time
      required:
      - id
      - provider
    DiscoveryActionsResponse:
      type: object
      description: Discovery actions response.
      additionalProperties: false
      properties:
        ok:
          const: true
        actions:
          type: array
          description: Available actions.
          items:
            $ref: '#/components/schemas/DiscoveryAction'
      required:
      - ok
      - actions
    WorkspaceHealthResponse:
      type: object
      description: Workspace health response.
      additionalProperties: true
      properties:
        ok:
          const: true
        health:
          type: object
          additionalProperties: true
      required:
      - ok
      - health
    ConnectionResponse:
      type: object
      description: Connection response.
      additionalProperties: true
      properties:
        ok:
          const: true
        connection:
          $ref: '#/components/schemas/Connection'
        account:
          $ref: '#/components/schemas/ConnectedAccount'
      required:
      - ok
    AccountsResponse:
      type: object
      description: Connected accounts response.
      additionalProperties: false
      properties:
        ok:
          const: true
        accounts:
          type: array
          description: Connected accounts.
          items:
            $ref: '#/components/schemas/ConnectedAccount'
      required:
      - ok
      - accounts
    ErrorResponse:
      type: object
      description: Standard error response returned by JSON API routes.
      additionalProperties: false
      properties:
        ok:
          const: false
          description: Always false for errors.
        code:
          type:
          - string
          - 'null'
          description: Stable machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type:
          - object
          - array
          - string
          - number
          - boolean
          - 'null'
          description: Optional route-specific details.
      required:
      - ok
      - message
    ActionResultResponse:
      type: object
      description: Discovery action result response.
      additionalProperties: true
      properties:
        ok:
          const: true
        result:
          type: object
          additionalProperties: true
      required:
      - ok
      - result
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SocialClaw API key
    DashboardSession:
      type: apiKey
      in: cookie
      name: socialclaw_dash_session
    WebhookSignature:
      type: apiKey
      in: header
      name: x-signature
externalDocs:
  description: Human-readable SocialClaw API documentation.
  url: https://getsocialclaw.com/docs/api
x-provenance:
  method: harvested
  publisher: SocialClaw
  source: https://getsocialclaw.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)