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_id*string

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

Length1 <= length
toolkits?|

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

auth_configs?

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_accounts?

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_connections?

Configuration for connection management settings

Default{"enable":true,"enable_wait_for_connections":false}
tools?

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

tags?|

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.

workbench?

Configuration for workbench behavior

Default{"enable_proxy_execution":true}
experimental?

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"
    ]
  }
}