Tool Router

Patch a tool router session config (v3.1)

Changed on

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.

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

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3.1/tool_router/session/{session_id}
  • Auth
    API key in header x-api-key

Path parameters

session_idstring toolRouterSessionId required

The unique identifier of the tool router session

Example:trs_1a2b3c4d5e6f

Request body

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 nullable

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, 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.

Example request

{
  "toolkits": {
    "enable": [
      "gmail",
      "slack",
      "github"
    ],
    "require_approval": [
      "github"
    ]
  },
  "auth_configs": {
    "gmail": "ac_1a2b3c4d5e6f",
    "slack": "ac_7g8h9i0j1k2l"
  },
  "instant": {
    "toolkits": {
      "enable": [
        "gmail",
        "slack",
        "github"
      ]
    }
  },
  "manage_connections": {
    "enable": true,
    "callback_url": "https://your-app.com/auth/callback"
  },
  "tags": {
    "require_approval": [
      "destructiveHint"
    ]
  },
  "workbench": {
    "enable": true,
    "enable_proxy_execution": true,
    "auto_offload_threshold": 20000,
    "sandbox_size": "large"
  },
  "multi_account": {
    "enable": true,
    "max_accounts_per_toolkit": 5
  },
  "proxy_execute": {
    "enable": true
  }
}

Response

Session config successfully patched.

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

  • d0a2f1ee8fd2Revision changes
    • breaking

      the request property type changed from no type to array

    • warning

      removed subschema #2 from the request property allOf list

    • info

      the request property became nullable

  • 798d44375fdcRevision changes
    • breaking

      removed subschema #1 subschema #2 from the ///// request property oneOf list

    • breaking

      added subschema #1 subschema #2 to the // response property oneOf list for the response status

    • info

      added subschema #1 subschema #2 to the ///// request property oneOf list

    • info

      removed subschema #1 subschema #2 from the // response property oneOf list for the response status