Skip to main content
PATCH
Patch a tool router session config (v3.1)

Authorizations

x-api-key
string
header
default:your-project-api-key
required

Your Composio project API key. Create or copy it from the Composio dashboard.

Path Parameters

session_id
string<toolRouterSessionId>
required

The unique identifier of the tool router session

Example:

"trs_1a2b3c4d5e6f"

Body

application/json
toolkits
object

Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive. Experimentally, it can also list toolkits whose tools need approval, with or without a filter.

auth_configs
object

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

Example:
connected_accounts
object | null

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.

instant

Controls instant usage, subject to project permission and session toolkit and tool restrictions. False disables instant 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.

Available options:
false
manage_connections
object | null
tools
object

Tool-level configuration per toolkit. Allows you to enable, disable, or filter by tags for specific tools within each toolkit, and experimentally to list tools that need approval. Every tool slug 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.

tags

Session-wide tags for filtering tools. Array format is treated as an enabled list. Object format supports enable (a tool must have at least one) and disable (a tool must have none), and experimentally the tags whose tools need approval. If a toolkit sets tools.<toolkit>.tags, its tools use that object instead of this one.

Available options:
readOnlyHint,
createHint,
updateHint,
destructiveHint,
idempotentHint,
openWorldHint
Example:
workbench
object | null
multi_account
object | null
proxy_execute
object | null
preload
object

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.

execute
object
hooks
object[] | null

Hooks that run on this session's tool calls. A hook can block a call before it runs, or block its result before the agent sees it.

Maximum array length: 20
experimental
object | null

Response

Session config successfully patched.

session_id
string<toolRouterSessionId>
required

The identifier of the session

Example:

"trs_1a2b3c4d5e6f"

mcp
object
required
tool_router_tools
string[]
required

List of available tools in this session

config
object
required

The configuration used to create this session

config_version
integer
required

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

experimental
object

Experimental v3.1 features

warnings
object[]

Advisory list — the session exists and is usable, but the listed issues may warrant attention.

Example: