Sign in
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.1/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

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.

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

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

Changes

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

  • 589a7d115a5e1See the full diff
    • ○

      the endpoint scheme security UserApiKeyAuth was removed from the API

      api-security-removed

  • 6ccbbc3d49b935See the full diff
    • ▲

      the connected_accounts/additionalProperties/ request property's minItems was increased to 1

      request-property-min-items-increased

    • ▲

      the connected_accounts/additionalProperties/ request property type/format changed from string/connectedAccountId to array/

      request-property-type-changed

    • ▲

      the config/connected_accounts/additionalProperties/ response's property type/format changed from string/connectedAccountId to array/ for status 201

      response-property-type-changed

    • ○

      the endpoint scheme security CookieAuth was removed from the API

      api-security-removed

    • ○

      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

    • ○

      added the new optional request property experimental/link_url_overwrite

      new-optional-request-property

  • 5a3709be76a717See the full diff
    • ▲

      response property config/preload/tools list-of-types was widened by adding types string to media type application/json of response 201

      response-property-list-of-types-widened

    • ○

      added the new optional request property execute

      new-optional-request-property

    • ○

      added the new optional request property search

      new-optional-request-property

    • ○

      added the new ask_always enum value to the request property experimental/permissions/overrides/additionalProperties/

      request-property-enum-value-added

    • ○

      added the new ask_once enum value to the request property experimental/permissions/overrides/additionalProperties/

      request-property-enum-value-added

    • ○

      request property preload/tools list-of-types was widened by adding types string to media type application/json

      request-property-list-of-types-widened

    • ○

      added the required property config/execute to the response with the 201 status

      response-required-property-added

    • ○

      added the required property config/search to the response with the 201 status

      response-required-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 52c71f747c651See the full diff
    • ○

      endpoint added

      endpoint-added