Tool Router

Attach to an existing tool router session (v3.1)

Fetch an existing tool router session by ID.

post/api/v3.1/tool_router/session/{session_id}/attach

Path parameters

session_idstring toolRouterSessionId required

The unique identifier of the tool router session

Example:trs_1a2b3c4d5e6f

The unique identifier of the tool router session

Request body

Example request

{
  "experimental": {
    "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 attached. Returns the session payload.

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 5 of the 61 revisions of this API.29

Jul 15, 20265c81af3844291See the full diff
- ○
  removed the non-success response with the status 403
  response-non-success-status-removed
Jun 17, 2026589a7d115a5e2See the full diff
- ○
  the endpoint scheme security CookieAuth was removed from the API
  api-security-removed
- ○
  the endpoint scheme security UserApiKeyAuth was removed from the API
  api-security-removed
May 6, 20266ccbbc3d49b913See the full diff
- ▲
  the config/connected_accounts/additionalProperties/ response's property type/format changed from string/connectedAccountId to array/ for status 200
  response-property-type-changed
- ○
  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
May 5, 20265a3709be76a712See the full diff
- ▲
  response property config/preload/tools list-of-types was widened by adding types string to media type application/json of response 200
  response-property-list-of-types-widened
- ○
  added the required property config/execute to the response with the 200 status
  response-required-property-added
- ○
  added the required property config/search to the response with the 200 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
May 5, 202652c71f747c651See the full diff
- ○
  endpoint added
  endpoint-added

Full history