Tool Router

Execute a tool within a tool router session

Execute a tool (meta or app) within an existing tool router session.

post/api/v3.1/tool_router/session/{session_id}/execute

Path parameters

session_idstring toolRouterSessionId

The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.

Example:trs_LX9uJKBinWWr

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

Request body

tool_slugstring required

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.

Example request

{
  "tool_slug": "GITHUB_CREATE_AN_ISSUE",
  "arguments": {
    "repository": "octocat/Hello-World",
    "workflow_id": "main.yml",
    "ref": "main",
    "inputs": {
      "environment": "production"
    }
  },
  "account": "coup_hurricane_dal_analytical",
  "enable_auto_workbench_offload": true,
  "experimental": {
    "custom_toolkits": [
      {
        "slug": "ecommerce",
        "name": "E-Commerce API",
        "description": "Internal e-commerce API for order management and fulfillment",
        "tools": [
          {
            "slug": "GET_CUSTOMER_ORDERS",
            "name": "Get Customer Orders",
            "description": "Fetch recent orders for a customer by their email address",
            "input_schema": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string",
                  "description": "Customer email"
                }
              },
              "required": [
                "email"
              ]
            }
          }
        ]
      }
    ],
    "custom_tools": [
      {
        "slug": "GET_IMPORTANT_EMAILS",
        "name": "Get Important Emails",
        "description": "Fetch emails marked as important from the last 24 hours",
        "input_schema": {
          "type": "object",
          "properties": {
            "limit": {
              "type": "number",
              "description": "Max results to return"
            }
          }
        },
        "extends_toolkit": "gmail"
      }
    ]
  }
}

Response

Successfully executed the tool. Returns execution result, logs, and status.

dataobject required

The data returned by the tool execution

errorstring nullable required

Error message if the execution failed, null otherwise

log_idstring required

Unique identifier for the execution log

Example response

{
  "data": {
    "message": "Hello, World!",
    "status": "success"
  },
  "log_id": "log_abc123xyz"
}

Changes

Changed in 4 of the 61 revisions of this API.6

Jun 17, 2026589a7d115a5e1See the full diff
- ○
  the endpoint scheme security UserApiKeyAuth was removed from the API
  api-security-removed
May 23, 2026b7d6dfeda6161See the full diff
- ○
  the endpoint scheme security CookieAuth was removed from the API
  api-security-removed
May 6, 20266ccbbc3d49b93See the full diff
- ○
  added the new optional request property experimental/custom_toolkits/items/preload
  new-optional-request-property
- ○
  added the new optional request property experimental/custom_toolkits/items/tools/items/preload
  new-optional-request-property
- ○
  added the new optional request property experimental/custom_tools/items/preload
  new-optional-request-property
May 5, 202652c71f747c651See the full diff
- ○
  endpoint added
  endpoint-added

Full history