API ReferenceTool Router

Execute a tool within a tool router sessionv3.0

POST
/api/v3/tool_router/session/{session_id}/execute

Executes a specific tool within a tool router session. This is the primary execution endpoint for both meta tools and app tools exposed by the session. The toolkit is automatically inferred from the tool slug. For app tools, the tool must belong to an allowed toolkit and must not be disabled in the session configuration. The endpoint validates permissions, resolves connected accounts when needed, and executes the tool with the session context. The top-level account field applies only to direct app tool execution in multi-account sessions. Meta/helper tools either ignore it or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.

Authorization

x-api-key<token>

Project API key authentication

In: header

Path Parameters

session_idstring

Tool router session ID (required for public API, optional for internal - injected by middleware)

Format: toolRouterSessionId

Request Body

application/json

tool_slugstringRequired

The unique slug identifier of the tool to execute. Supports both meta tools and app tools exposed by the session.

argumentsobject

The arguments required by the tool

accountstring

Account identifier to specify which connected account to use for direct tool execution. Use the account ID (e.g. "coup_hurricane_dal_analytical") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts. Meta/helper tools either ignore this top-level field or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.

enable_auto_workbench_offloadboolean

When true, direct non-meta tool execution may return a workbench offload preview if the response exceeds the configured threshold and the session workbench is enabled. When omitted or false, direct tool execution returns the normal inline response. Meta/helper tools are unaffected, and COMPOSIO_MULTI_EXECUTE_TOOL uses session.workbench configuration for its own batch-level offload behavior.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://backend.composio.dev/api/v3/tool_router/session/{session_id}/execute" \  -H "Content-Type: application/json" \  -d '{    "tool_slug": "GITHUB_CREATE_AN_ISSUE"  }'
{
  "data": {
    "message": "Hello, World!",
    "status": "success"
  },
  "error": "string",
  "log_id": "log_abc123xyz"
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}
Edit this page on GitHub