API REFERENCE

Execute Connector Action

On this page

POST/api/connectors/actions

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 and pass the returned descriptor.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/connectors/actions' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionSlug": "string",
  "parameters": {}
}'

Request body required

Action to execute and the parameters for it

application/json

actionSlugstringrequired

Action slug from GET /api/connectors/actions. Always UPPERCASE_SNAKE_CASE (e.g. GOOGLESHEETS_WRITE_SPREADSHEET). Required.

parametersobjectrequired

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.

account_idstring

Optional account ID to execute the action on a different account (e.g., an artist). The authenticated account must have access. Omit to execute on your own account.

format: uuid

Responses

200Action executed successfully

application/json

successbooleanrequired

resultobjectrequired

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.

executedAtstring

ISO 8601 timestamp of when the action was executed server-side.

format: date-time

400Bad request — missing or invalid parameters (e.g. parameters does not match the action's schema)

application/json

errorintegerrequired

format: int32

messagestringrequired

401Unauthorized — invalid or missing API key

application/json

errorintegerrequired

format: int32

messagestringrequired

403Forbidden — no access to the specified account

application/json

errorintegerrequired

format: int32

messagestringrequired

404Action slug not found in any of the account's connectors

application/json

errorintegerrequired

format: int32

messagestringrequired

409The action's parent connector is not currently connected. Authorize it via POST /api/connectors before retrying.

application/json

errorintegerrequired

format: int32

messagestringrequired

502Upstream connector failure (the third-party service errored or timed out)

application/json

errorintegerrequired

format: int32

messagestringrequired

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json

View operation source

json

{
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "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"
          }
        }
      }
    }
  }
}