API ReferenceSessions (prev Tool Router)

Patch a tool router session config (v3.1)v3.1

PATCH
/api/v3.1/tool_router/session/{session_id}

Partially updates an existing tool router session. Inline fields update only the supplied settings. Alternatively, experimental.session_config_id applies the latest active saved config from this project, replacing toolkit, tool, and tag access while preserving other settings. Later saved-config edits do not sync automatically. Uses optimistic concurrency control and retains the previous policy in config history.

Authorization

ApiKeyAuth
x-api-key<token>

Project API key authentication

In: header

Path Parameters

session_idstringRequired

The unique identifier of the tool router session

Format: toolRouterSessionId

Request Body

application/json

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_accountsnullable object

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.

premium_usageenum | object

Controls premium usage, subject to project permission and session toolkit and tool restrictions. False disables premium usage. Omission on create or an empty object enables it with charges hidden. On PATCH, omitted fields are preserved; an object re-enables a disabled setting.

manage_connectionsnullable object
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.

workbenchnullable object
multi_accountnullable object
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
executeobject
experimentalnullable objectExperimental

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/v3.1/tool_router/session/trs_1a2b3c4d5e6f" \  -H "Content-Type: application/json" \  -d '{}'
{  "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"    },    "premium_usage": false,    "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",            "preload": true          }        ],        "preload": true      }    ],    "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",        "preload": true      }    ],    "source_session_config": {      "id": "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."    }  ]}
Edit this page on GitHub