> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Connector Action

> Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific. To attach an image to a `file_uploadable` parameter (e.g. `images`), first stage it with [Upload Connector File](/api-reference/connectors/upload-file) and pass the returned descriptor.



## OpenAPI

````yaml api-reference/openapi/social.json POST /api/connectors/actions
openapi: 3.1.0
info:
  title: Recoup API - Social
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/connectors/actions:
    post:
      description: >-
        Execute a connector action with the given parameters. The `actionSlug`
        must come from a prior call to GET /api/connectors/actions, and
        `parameters` must match the `parameters` JSON Schema returned for that
        action. The action's parent connector must be currently connected
        (`isConnected: true` in the catalog) — otherwise this endpoint returns
        409. The `result` field passes through whatever the underlying connector
        returns; its shape is action-specific. To attach an image to a
        `file_uploadable` parameter (e.g. `images`), first stage it with [Upload
        Connector File](/api-reference/connectors/upload-file) and pass the
        returned descriptor.
      requestBody:
        description: Action to execute and the parameters for it
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteConnectorActionRequest'
      responses:
        '200':
          description: Action executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteConnectorActionResponse'
        '400':
          description: >-
            Bad request — missing or invalid parameters (e.g. `parameters` does
            not match the action's schema)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — no access to the specified account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Action slug not found in any of the account's connectors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            The action's parent connector is not currently connected. Authorize
            it via POST /api/connectors before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            Upstream connector failure (the third-party service errored or timed
            out)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    ExecuteConnectorActionRequest:
      type: object
      required:
        - actionSlug
        - parameters
      properties:
        actionSlug:
          type: string
          description: >-
            Action slug from GET /api/connectors/actions. Always
            UPPERCASE_SNAKE_CASE (e.g. `GOOGLESHEETS_WRITE_SPREADSHEET`).
            Required.
        parameters:
          type: object
          description: >-
            Action-specific parameters matching the `parameters` JSON Schema
            returned by GET /api/connectors/actions for this `actionSlug`. The
            connector validates these against the cached schema before executing
            — invalid shapes return 400. Required.
          additionalProperties: true
        account_id:
          type: string
          format: uuid
          description: >-
            Optional account ID to execute the action on a different account
            (e.g., an artist or workspace). The authenticated account must have
            access. Omit to execute on your own account.
    ExecuteConnectorActionResponse:
      type: object
      required:
        - success
        - result
      properties:
        success:
          type: boolean
        result:
          type: object
          additionalProperties: true
          description: >-
            Pass-through of the underlying connector's response payload. Shape
            is action-specific — consult the action's parameters schema and the
            third-party service's own documentation for what to expect. The
            server-side wrapper does not transform this field.
        executedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the action was executed server-side.
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).
    bearerAuth:
      type: http
      scheme: bearer

````