API ReferenceTool Router

Create a new tool router session

Markdown
POST/api/v3/tool_router/session

Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.

Authorization

ApiKeyAuth
x-api-key<token>

API key authentication

In: header

Request Body

application/json

user_idstringRequired

The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address

toolkitsobject | object

Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive.

auth_configsobject

The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed

connected_accountsobject

The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed

manage_connectionsobject

Configuration for connection management settings

Default: {"enable":true,"enable_wait_for_connections":false}
toolsobject

Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit

tagsenum[] | object

Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.

workbenchobject

Configuration for workbench behavior

Default: {"enable_proxy_execution":true}
experimentalobject

Experimental features - not stable, may be modified or removed in future versions.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://backend.composio.dev/api/v3/tool_router/session" \  -H "Content-Type: application/json" \  -d '{    "user_id": "user_123456789"  }'
{
  "session_id": "trs_123456789",
  "mcp": {
    "type": "http",
    "url": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"
  },
  "tool_router_tools": [
    "string"
  ],
  "config": {
    "user_id": "string",
    "toolkits": {
      "enabled": [
        "string"
      ]
    },
    "auth_configs": {
      "property1": "string",
      "property2": "string"
    },
    "connected_accounts": {
      "property1": "string",
      "property2": "string"
    },
    "manage_connections": {
      "enabled": true,
      "callback_url": "http://example.com",
      "enable_wait_for_connections": false
    },
    "tools": {
      "property1": {
        "enabled": [
          "string"
        ]
      },
      "property2": {
        "enabled": [
          "string"
        ]
      }
    },
    "tags": {
      "enabled": [
        "readOnlyHint"
      ],
      "disabled": [
        "readOnlyHint"
      ]
    },
    "workbench": {
      "proxy_execution_enabled": true
    }
  },
  "experimental": {
    "assistive_prompt": "You are an AI agent that completes user tasks by calling Composio ToolRouter meta-tools..."
  }
}
{
  "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"
    ]
  }
}