API ReferenceTool Router

Create a new tool router sessionv3.1

Markdown
POST
/api/v3.1/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

x-api-key<token>

Project 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, as an array of nano-IDs per toolkit. This overrides the default behaviour and pins specific connected accounts when toolkits are executed. Each account must exist (not deleted or disabled) and belong to the same user_id as the session. Multi-account sessions can pin multiple; non-multi-account sessions are capped at length 1.

manage_connectionsobject

Configuration for connection management settings

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

Tool-level configuration per toolkit. Allows you to enable, disable, or filter by tags for specific tools within each toolkit. Every slug passed in enable / disable must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.

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":true,"enable_proxy_execution":true}
multi_accountobject

Configure multi-account behavior. When enabled, users can connect multiple accounts per toolkit.

experimentalobject

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

preloadobject

Preload configuration. Use an explicit list for frequently used tool slugs, or "all" to dynamically expose every app tool allowed by positive toolkits/tools/tags filters.

searchobject
Default: {"enable":true}
executeobject
Default: {"enable_multi_execute":true}

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://backend.composio.dev/api/v3.1/tool_router/session" \  -H "Content-Type: application/json" \  -d '{    "user_id": "user_123456789"  }'
{
  "session_id": "trs_1a2b3c4d5e6f",
  "mcp": {
    "type": "http",
    "url": "https://app.composio.dev/tool_router/v3/trs_1a2b3c4d5e6f/mcp"
  },
  "tool_router_tools": [
    "string"
  ],
  "config": {
    "user_id": "string",
    "toolkits": {
      "enabled": [
        "string"
      ]
    },
    "auth_configs": {
      "property1": "string",
      "property2": "string"
    },
    "manage_connections": {
      "enabled": true,
      "callback_url": "http://example.com",
      "enable_wait_for_connections": false,
      "enable_connection_removal": true
    },
    "tools": {
      "property1": {
        "enabled": [
          "string"
        ]
      },
      "property2": {
        "enabled": [
          "string"
        ]
      }
    },
    "tags": {
      "enabled": [
        "readOnlyHint"
      ],
      "disabled": [
        "readOnlyHint"
      ]
    },
    "workbench": {
      "enable": true,
      "proxy_execution_enabled": true
    },
    "multi_account": {
      "enable": true,
      "max_accounts_per_toolkit": 0,
      "require_explicit_selection": true
    },
    "preload": {
      "tools": [
        "string"
      ]
    },
    "connected_accounts": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "search": {
      "enable": true
    },
    "execute": {
      "enable_multi_execute": true
    }
  },
  "config_version": 0,
  "experimental": {
    "assistive_prompt": "string",
    "custom_toolkits": [
      {
        "slug": "string",
        "name": "string",
        "description": "string",
        "tools": [
          {
            "slug": "string",
            "name": "string",
            "description": "string",
            "input_schema": {
              "property1": null,
              "property2": null
            },
            "output_schema": {
              "property1": null,
              "property2": null
            },
            "original_slug": "string"
          }
        ]
      }
    ],
    "custom_tools": [
      {
        "slug": "string",
        "name": "string",
        "description": "string",
        "input_schema": {
          "property1": null,
          "property2": null
        },
        "output_schema": {
          "property1": null,
          "property2": null
        },
        "extends_toolkit": "string",
        "original_slug": "string"
      }
    ]
  },
  "warnings": [
    {
      "code": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE",
      "message": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 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"
    ]
  }
}
{
  "error": {
    "message": "string",
    "code": 0,
    "slug": "string",
    "status": 0,
    "request_id": "string",
    "suggested_fix": "string",
    "errors": [
      "string"
    ]
  }
}