# Patch a tool router session config

**Documentation:** /reference/v3/api-reference/tool-router/patchToolRouterSessionBySessionId

Partially updates the configuration of an existing tool router session. Only the fields provided in the request body will be updated. Uses optimistic concurrency control to prevent lost updates. The previous config is stored in config history.

---

## PATCH `/api/v3/tool_router/session/{session_id}`

**Endpoint:** `https://backend.composio.dev/api/v3/tool_router/session/{session_id}`

**Summary:** Patch a tool router session config

Partially updates the configuration of an existing tool router session. Only the fields provided in the request body will be updated. Uses optimistic concurrency control to prevent lost updates. The previous config is stored in config history.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Path Parameters

- `session_id` (string (toolRouterSessionId)) *(required)*: The unique identifier of the tool router session

### Request Body

**Schema:**

- `toolkits` (any): Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive.
- `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
  - `[key: string]` (string (authConfigId))
- `connected_accounts` (object): Per-toolkit connected account override (single nano-ID). Each connected account must exist (not deleted or disabled) and belong to the same `user_id` as the session.
  - `[key: string]` (string)
- `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. 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.
  - `[key: string]` (any)
- `tags` (any): 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.
- `workbench` (object,null)
- `multi_account` (object,null)
- `preload` (object): Preload configuration for Composio tools. Controls which tools appear in `session.tools` and the MCP server tool list so the agent can call them directly without going through search first. Custom tools use `preload` on the custom tool/toolkit definition instead. Not supported when multi-account is enabled. Each preloaded tool adds to the agent context window, so keep the list at or under ~20 tools.
  - `tools` (array<string>): Composio tool slugs to preload. Each slug must be allowed by the session filters (`toolkits`, `tools`, `tags`) — unknown, blocked, meta, or custom slugs return a 400 at session creation.
- `experimental` (object,null)

**Example:**

```json
{
  "toolkits": null,
  "auth_configs": {
    "key": "string"
  },
  "connected_accounts": {
    "key": "string"
  },
  "manage_connections": null,
  "tools": {
    "key": null
  },
  "tags": null,
  "workbench": null,
  "multi_account": null,
  "preload": {
    "tools": [
      "string"
    ]
  },
  "experimental": null
}
```

### Responses

#### 200 - Session config successfully patched.

**Response Schema:**

- `session_id` (string (toolRouterSessionId)) *(required)*: The identifier of the session
- `mcp` (object) *(required)*
  - `type` (enum: "http") *(required)*: The type of the MCP server. Can be http
  - `url` (string (uri)) *(required)*: The URL of the MCP server
- `tool_router_tools` (array<string>) *(required)*: List of available tools in this session
- `config` (object) *(required)*: The session configuration including user, toolkits, and overrides
  - `user_id` (string) *(required)*: User identifier for this session
  - `toolkits` (any): Toolkit configuration - either enabled list or disabled list
  - `auth_configs` (object): Auth config overrides per toolkit
    - `[key: string]` (string (authConfigId))
  - `connected_accounts` (object): Per-toolkit connected account override (single nano-ID). Returns the first override when multi-account is enabled; see `all_connected_accounts` for the full list.
    - `[key: string]` (string (connectedAccountId))
  - `all_connected_accounts` (object): Full per-toolkit connected account overrides as arrays. Populated whenever `connected_accounts` is non-empty; carries the complete list when multi-account is enabled.
    - `[key: string]` (array<string (connectedAccountId)>)
  - `manage_connections` (object): Manage connections configuration
    - `enabled` (boolean): Whether to enable the connection manager for automatic connection handling
    - `callback_url` (string (uri)): Custom callback URL for connected account auth flows
    - `enable_wait_for_connections` (boolean): Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models.
    - `enable_connection_removal` (boolean): Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS. Default true.
  - `tools` (object): Tool-level configuration per toolkit
    - `[key: string]` (any)
  - `tags` (object): MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied.
    - `enabled` (array<enum: "readOnlyHint" | "destructiveHint" | "idempotentHint" | ...>): Tags that the tool must have at least one of
    - `disabled` (array<enum: "readOnlyHint" | "destructiveHint" | "idempotentHint" | ...>): Tags that the tool must NOT have any of
  - `workbench` (object): Workbench configuration
    - `enable` (boolean): Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
    - `proxy_execution_enabled` (boolean): Whether proxy execution is enabled in the workbench
    - `auto_offload_threshold` (number): Character threshold after which tool execution response are saved to a file in workbench. Default is 20k.
    - `sandbox_size` (enum: "standard" | "medium" | "large" | ...): Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
  - `multi_account` (object): Multi-account configuration for this session.
    - `enable` (boolean): When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.
    - `max_accounts_per_toolkit` (integer): Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled.
    - `require_explicit_selection` (boolean): When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account.
  - `preload` (object) *(required)*: Preload configuration. Controls which tools appear in `session.tools` and the MCP server tool list, callable directly without going through search. Each preloaded tool adds to the agent context — roughly ≤20 tools is recommended. Always present in the response (empty `tools: []` when the session was created without a preload config).
    - `tools` (array<string>) *(required)*: Tool slugs preloaded for this session. Appear in `session.tools` and the MCP server tool list, callable directly without going through search. Empty array when no preload was configured.
- `config_version` (integer) *(required)*: Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control.
- `experimental` (object): Experimental features
  - `assistive_prompt` (string): The assistive system prompt for the tool router session
  - `custom_toolkits` (array<object>): User-defined custom toolkits with grouped tools (no-auth)
    - Array items:
      - `slug` (string) *(required)*
      - `name` (string) *(required)*
      - `description` (string) *(required)*
      - `tools` (array<object>) *(required)*
        - Array items:
          - ...
  - `custom_tools` (array<object>): Custom tools — standalone or extending Composio toolkits
    - Array items:
      - `slug` (string) *(required)*: Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
      - `name` (string) *(required)*
      - `description` (string) *(required)*
      - `input_schema` (object) *(required)*
        - `[key: string]` (any)
      - `output_schema` (object)
        - `[key: string]` (any)
      - `extends_toolkit` (string)
      - `original_slug` (string) *(required)*: Original tool slug as provided by the user
- `warnings` (array<object>): Advisory list — the session exists and is usable, but the listed issues may warrant attention.
  - Array items:
    - `code` (enum: "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE") *(required)*: Stable machine code identifying the advisory. Safe to switch on in client code.
    - `message` (string) *(required)*: Human-readable description of the advisory. Suitable for logging or surfacing to end users.

**Example Response:**

```json
{
  "session_id": "string",
  "mcp": {
    "type": "http",
    "url": "https://example.com"
  },
  "tool_router_tools": [
    "string"
  ],
  "config": {
    "user_id": "string",
    "toolkits": null,
    "auth_configs": {
      "key": "string"
    },
    "connected_accounts": {
      "key": "string"
    },
    "all_connected_accounts": {
      "key": [
        "..."
      ]
    },
    "manage_connections": {
      "enabled": true,
      "callback_url": "https://example.com",
      "enable_wait_for_connections": false,
      "enable_connection_removal": true
    },
    "tools": {
      "key": null
    },
    "tags": {
      "enabled": [
        "..."
      ],
      "disabled": [
        "..."
      ]
    },
    "workbench": {
      "enable": true,
      "proxy_execution_enabled": true
    },
    "multi_account": {
      "enable": true,
      "max_accounts_per_toolkit": 1,
      "require_explicit_selection": true
    },
    "preload": {
      "tools": [
        "..."
      ]
    }
  },
  "config_version": 1,
  "experimental": {
    "assistive_prompt": "string",
    "custom_toolkits": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "tools": "..."
      }
    ],
    "custom_tools": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "input_schema": "...",
        "output_schema": "...",
        "extends_toolkit": "...",
        "original_slug": "..."
      }
    ]
  },
  "warnings": []
}
```

#### 400 - Bad request. Invalid config values.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Session not found.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 408 - Request timeout while validating patch.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 409 - Config version conflict. Re-fetch the session and retry.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X PATCH "https://backend.composio.dev/api/v3/tool_router/session/string" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolkits": null,
    "auth_configs": {
      "key": "string"
    },
    "connected_accounts": {
      "key": "string"
    },
    "manage_connections": null,
    "tools": {
      "key": null
    },
    "tags": null,
    "workbench": null,
    "multi_account": null,
    "preload": {
      "tools": [
        "string"
      ]
    },
    "experimental": null
  }'
```