v2

latestOpenAPI 3.0.0Proprietary2026-08-07936826.0 KB

Tool Router

Create a new 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.

post/api/v3/tool_router/session

Request body

user_idstring required

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

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

Per-toolkit connected account override (single nano-ID). Each connected account must exist (not deleted or disabled) and belong to the same user_id as the session.

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.

Example request

{
  "user_id": "user_123456789",
  "toolkits": {
    "enable": [
      "gmail",
      "slack",
      "github"
    ]
  },
  "auth_configs": {
    "gmail": "ac_1a2b3c4d5e6f",
    "slack": "ac_7g8h9i0j1k2l"
  },
  "connected_accounts": {
    "github": "ca_3m4n5o6p7q8r"
  },
  "manage_connections": {
    "enable": true,
    "callback_url": "https://your-app.com/auth/callback"
  },
  "tools": {
    "gmail": {
      "enable": [
        "GMAIL_SEND_EMAIL",
        "GMAIL_FETCH_EMAILS"
      ]
    },
    "slack": {
      "disable": [
        "SLACK_ADD_EMOJI"
      ]
    },
    "slackbot": {
      "tags": {
        "enable": [
          "destructiveHint"
        ],
        "disable": [
          "openWorldHint"
        ]
      }
    }
  },
  "workbench": {
    "enable": true,
    "enable_proxy_execution": true,
    "auto_offload_threshold": 20000,
    "sandbox_size": "standard"
  },
  "multi_account": {
    "enable": true,
    "max_accounts_per_toolkit": 5
  },
  "experimental": {
    "assistive_prompt_config": {
      "user_timezone": "America/New_York"
    },
    "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"
      }
    ]
  },
  "preload": {
    "tools": [
      "GMAIL_FETCH_EMAILS",
      "SLACK_SEND_MESSAGE"
    ]
  }
}

Response

Session successfully created. Returns the session ID and MCP server URL for the created session.

session_idstring toolRouterSessionId required

The identifier of the session

tool_router_toolsstring[] required

List of available tools in this session

config_versioninteger required

Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control.

Example response

{
  "session_id": "trs_1a2b3c4d5e6f",
  "mcp": {
    "url": "https://app.composio.dev/tool_router/v3/trs_1a2b3c4d5e6f/mcp"
  },
  "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."
    }
  ]
}