> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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



## OpenAPI

````yaml /api-reference/openapi.json patch /api/v3.1/tool_router/session/{session_id}
openapi: 3.1.0
info:
  version: 3.1.0
  title: Composio Platform API v3.1
  description: >-
    Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints
    default to the latest tool version.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/tool_router/session/{session_id}:
    patch:
      tags:
        - Tool Router
      summary: Patch a tool router session config (v3.1)
      description: >-
        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.
      operationId: patchToolRouterSessionBySessionId
      parameters:
        - schema:
            type: string
            format: toolRouterSessionId
            description: The unique identifier of the tool router session
            example: trs_1a2b3c4d5e6f
          required: true
          description: The unique identifier of the tool router session
          name: session_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                toolkits:
                  anyOf:
                    - type: object
                      properties:
                        enable:
                          type: array
                          items:
                            type: string
                          description: Only these specific toolkits will be enabled
                          example:
                            - gmail
                            - slack
                            - github
                        require_approval:
                          type: array
                          items:
                            type: string
                          minItems: 1
                          description: >-
                            Tool calls matched here pause until the user
                            approves them. A tool needs approval if its toolkit,
                            the tool itself or any of its tags is listed. A
                            toolkit's own lists in `tools` replace the
                            session-wide tag list for that toolkit.
                          x-experimental: true
                          example:
                            - github
                      required:
                        - enable
                      additionalProperties: false
                      description: Enable only specific toolkits (allowlist)
                    - type: object
                      properties:
                        disable:
                          type: array
                          items:
                            type: string
                          description: These specific toolkits will be disabled
                          example:
                            - gmail
                            - slack
                        require_approval:
                          type: array
                          items:
                            type: string
                          minItems: 1
                          description: >-
                            Tool calls matched here pause until the user
                            approves them. A tool needs approval if its toolkit,
                            the tool itself or any of its tags is listed. A
                            toolkit's own lists in `tools` replace the
                            session-wide tag list for that toolkit.
                          x-experimental: true
                          example:
                            - github
                      required:
                        - disable
                      additionalProperties: false
                      description: Disable specific toolkits (denylist)
                    - type: object
                      properties:
                        require_approval:
                          type: array
                          items:
                            type: string
                          minItems: 1
                          description: >-
                            Tool calls matched here pause until the user
                            approves them. A tool needs approval if its toolkit,
                            the tool itself or any of its tags is listed. A
                            toolkit's own lists in `tools` replace the
                            session-wide tag list for that toolkit.
                          x-experimental: true
                          example:
                            - github
                      required:
                        - require_approval
                      additionalProperties: false
                  description: >-
                    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:
                  type: object
                  additionalProperties:
                    type: string
                    format: authConfigId
                  description: >-
                    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:
                    gmail: ac_1a2b3c4d5e6f
                    slack: ac_7g8h9i0j1k2l
                connected_accounts:
                  type:
                    - object
                    - 'null'
                  additionalProperties:
                    type: array
                    items:
                      type: string
                      format: connectedAccountId
                    minItems: 1
                  description: >-
                    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:
                  anyOf:
                    - type: boolean
                      enum:
                        - false
                    - type: object
                      properties:
                        toolkits:
                          anyOf:
                            - type: object
                              properties:
                                enable:
                                  type: array
                                  items:
                                    type: string
                                  description: Only these specific toolkits will be enabled
                                  example:
                                    - gmail
                                    - slack
                                    - github
                              required:
                                - enable
                              additionalProperties: false
                              description: Enable only specific toolkits (allowlist)
                            - type: object
                              properties:
                                disable:
                                  type: array
                                  items:
                                    type: string
                                  description: These specific toolkits will be disabled
                                  example:
                                    - gmail
                                    - slack
                              required:
                                - disable
                              additionalProperties: false
                              description: Disable specific toolkits (denylist)
                          description: >-
                            Toolkit configuration - specify either enable
                            toolkits (allowlist) or disable toolkits (denylist).
                            Mutually exclusive.
                        tools:
                          type: object
                          additionalProperties:
                            anyOf:
                              - type: object
                                properties:
                                  enable:
                                    type: array
                                    items:
                                      type: string
                                    description: >-
                                      Only these specific tools will be
                                      available for this toolkit
                                    example:
                                      - GMAIL_SEND_EMAIL
                                      - GMAIL_FETCH_EMAILS
                                required:
                                  - enable
                                additionalProperties: false
                              - type: object
                                properties:
                                  disable:
                                    type: array
                                    items:
                                      type: string
                                    description: >-
                                      These specific tools will be disabled for
                                      this toolkit
                                    example:
                                      - SLACK_ADD_EMOJI
                                required:
                                  - disable
                                additionalProperties: false
                          description: >-
                            Per-toolkit enable or disable lists that restrict
                            instant usage. Toolkits absent from the map have no
                            additional tool restriction. On PATCH, a supplied
                            map replaces all existing tool filters; an empty map
                            clears them, and omission preserves them.
                        return_instant_charge:
                          type: boolean
                          description: >-
                            Return the top-level instant_charge in session tool
                            responses when a charge is available. Defaults to
                            false on create; omission on PATCH preserves the
                            current value. Controls response visibility only; it
                            does not enable or disable instant usage.
                        return_prices_in_search:
                          type: boolean
                          description: >-
                            Experimental. Show each instant tool's price in tool
                            search results, under instant_account.prices.
                            Defaults to false on create; omit on PATCH to keep
                            the current value. Does not turn instant usage on or
                            off.
                          x-experimental: true
                      additionalProperties: false
                  description: >-
                    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.
                manage_connections:
                  type:
                    - object
                    - 'null'
                  properties:
                    enable:
                      type:
                        - boolean
                        - 'null'
                      description: >-
                        Whether to enable the connection manager for automatic
                        connection handling. If true, we will provide a tool
                        your agent can use to initiate connections to toolkits
                        if it doesnt exist. If set to false, then you have to
                        manage connections manually.
                      example: true
                    callback_url:
                      type: string
                      format: uri
                      description: >-
                        The URL to redirect to after a user completes
                        authentication for a connected account. This allows you
                        to handle the auth callback in your own application.
                      example: https://your-app.com/auth/callback
                    enable_wait_for_connections:
                      type:
                        - boolean
                        - 'null'
                      description: >-
                        When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is
                        available for agents to poll connection status after
                        sharing auth URLs. Default is false (disabled). May not
                        work reliably with GPT models.
                      example: false
                    enable_connection_removal:
                      type:
                        - boolean
                        - 'null'
                      description: >-
                        Enable the "remove" action in
                        COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected
                        accounts. Default true.
                  additionalProperties: false
                tools:
                  type: object
                  additionalProperties:
                    anyOf:
                      - type: object
                        properties:
                          enable:
                            type: array
                            items:
                              type: string
                            description: >-
                              Only these specific tools will be available for
                              this toolkit
                            example:
                              - GMAIL_SEND_EMAIL
                              - GMAIL_FETCH_EMAILS
                          require_approval:
                            type: array
                            items:
                              type: string
                            description: >-
                              Tool calls matched here pause until the user
                              approves them. Setting this toolkit's own list,
                              even an empty one, replaces the session-wide
                              `tags.require_approval` for its tools.
                            x-experimental: true
                            example:
                              - GITHUB_DELETE_A_REPOSITORY
                        required:
                          - enable
                        additionalProperties: false
                      - type: object
                        properties:
                          disable:
                            type: array
                            items:
                              type: string
                            description: >-
                              These specific tools will be disabled for this
                              toolkit
                            example:
                              - SLACK_ADD_EMOJI
                          require_approval:
                            type: array
                            items:
                              type: string
                            description: >-
                              Tool calls matched here pause until the user
                              approves them. Setting this toolkit's own list,
                              even an empty one, replaces the session-wide
                              `tags.require_approval` for its tools.
                            x-experimental: true
                            example:
                              - GITHUB_DELETE_A_REPOSITORY
                        required:
                          - disable
                        additionalProperties: false
                      - type: object
                        properties:
                          tags:
                            anyOf:
                              - type: array
                                items:
                                  type: string
                                  enum:
                                    - readOnlyHint
                                    - createHint
                                    - updateHint
                                    - destructiveHint
                                    - idempotentHint
                                    - openWorldHint
                              - type: object
                                properties:
                                  enable:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                        - readOnlyHint
                                        - createHint
                                        - updateHint
                                        - destructiveHint
                                        - idempotentHint
                                        - openWorldHint
                                  disable:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                        - readOnlyHint
                                        - createHint
                                        - updateHint
                                        - destructiveHint
                                        - idempotentHint
                                        - openWorldHint
                                  require_approval:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                        - readOnlyHint
                                        - createHint
                                        - updateHint
                                        - destructiveHint
                                        - idempotentHint
                                        - openWorldHint
                                    description: >-
                                      Tool calls matched here pause until the
                                      user approves them. Setting this toolkit's
                                      own list, even an empty one, replaces the
                                      session-wide `tags.require_approval` for
                                      its tools.
                                    x-experimental: true
                                    example:
                                      - destructiveHint
                            description: >-
                              Tags for this toolkit. Any `tags` object here
                              fully replaces the session-wide `tags` for this
                              toolkit, including one that only sets
                              `require_approval`. Array format is treated as an
                              enabled list.
                            example:
                              disable:
                                - openWorldHint
                              require_approval:
                                - destructiveHint
                          require_approval:
                            type: array
                            items:
                              type: string
                            description: >-
                              Tool calls matched here pause until the user
                              approves them. Setting this toolkit's own list,
                              even an empty one, replaces the session-wide
                              `tags.require_approval` for its tools.
                            x-experimental: true
                            example:
                              - GITHUB_DELETE_A_REPOSITORY
                        required:
                          - tags
                        additionalProperties: false
                      - type: object
                        properties:
                          require_approval:
                            type: array
                            items:
                              type: string
                            description: >-
                              Tool calls matched here pause until the user
                              approves them. Setting this toolkit's own list,
                              even an empty one, replaces the session-wide
                              `tags.require_approval` for its tools.
                            x-experimental: true
                            example:
                              - GITHUB_DELETE_A_REPOSITORY
                        required:
                          - require_approval
                        additionalProperties: false
                  description: >-
                    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:
                  anyOf:
                    - type: array
                      items:
                        type: string
                        enum:
                          - readOnlyHint
                          - createHint
                          - updateHint
                          - destructiveHint
                          - idempotentHint
                          - openWorldHint
                    - type: object
                      properties:
                        enable:
                          type: array
                          items:
                            type: string
                            enum:
                              - readOnlyHint
                              - createHint
                              - updateHint
                              - destructiveHint
                              - idempotentHint
                              - openWorldHint
                        disable:
                          type: array
                          items:
                            type: string
                            enum:
                              - readOnlyHint
                              - createHint
                              - updateHint
                              - destructiveHint
                              - idempotentHint
                              - openWorldHint
                        require_approval:
                          type: array
                          items:
                            type: string
                            enum:
                              - readOnlyHint
                              - createHint
                              - updateHint
                              - destructiveHint
                              - idempotentHint
                              - openWorldHint
                          minItems: 1
                          description: >-
                            Tool calls matched here pause until the user
                            approves them. A tool needs approval if its toolkit,
                            the tool itself or any of its tags is listed. A
                            toolkit's own lists in `tools` replace the
                            session-wide tag list for that toolkit.
                          x-experimental: true
                          example:
                            - destructiveHint
                  description: >-
                    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.
                  example:
                    disable:
                      - openWorldHint
                    require_approval:
                      - destructiveHint
                workbench:
                  type:
                    - object
                    - 'null'
                  properties:
                    enable:
                      type: boolean
                      description: >-
                        Set to false to disable the workbench entirely. When
                        disabled, no code execution tools are available in the
                        session.
                      example: true
                    enable_tool_execution:
                      type: boolean
                      description: >-
                        Whether Composio tool execution is enabled inside the
                        workbench. Defaults to true. When false,
                        run_composio_tool, invoke_llm, and web_search are
                        unavailable; Python analysis and file helpers remain
                        available. Proxy execution defaults to true and still
                        permits authenticated connected-app HTTP requests. Set
                        enable_proxy_execution to false as well to block both
                        Composio tool and proxy access through Workbench
                        credentials. These flags do not restrict network access
                        or independently supplied credentials. Changing this
                        flag recreates the sandbox: notebook state and local
                        files are lost, but /mnt/files/ persists. Tool
                        descriptions and search guidance reflect the updated
                        flag, but assistive_prompt is returned only at session
                        creation and is not regenerated by PATCH; callers must
                        update any previously retained prompt guidance.
                    enable_proxy_execution:
                      type: boolean
                      description: >-
                        Whether proxy execution is enabled. When enabled,
                        workbench can call URLs and APIs directly.
                      example: true
                    auto_offload_threshold:
                      type: number
                      description: >-
                        Character threshold for automatic offloading. When
                        workbench response exceeds this threshold, it will be
                        automatically offloaded. Default is picked automatically
                        based on the response size.
                      example: 20000
                      exclusiveMinimum: 0
                    sandbox_size:
                      type: string
                      enum:
                        - standard
                        - medium
                        - large
                        - xlarge
                      description: >-
                        Sandbox compute tier: standard (1 vCPU / 1 GB), medium
                        (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU /
                        8 GB). Patching this value recreates the sandbox on next
                        access — sandbox FS state is lost, but /mnt/files/ R2
                        mount persists.
                      example: large
                  additionalProperties: false
                multi_account:
                  type:
                    - object
                    - 'null'
                  properties:
                    enable:
                      type: boolean
                      description: >-
                        When true, enables multi-account mode for this session.
                        When not set, falls back to org/project-level
                        configuration.
                      example: true
                    max_accounts_per_toolkit:
                      type: integer
                      minimum: 2
                      maximum: 10
                      description: >-
                        Maximum number of connected accounts allowed per
                        toolkit. Must be between 2 and 10.
                      example: 5
                    require_explicit_selection:
                      type: boolean
                      description: >-
                        When true, the agent must explicitly select which
                        account to use. When false (default), the first/default
                        account is used automatically.
                      example: false
                  additionalProperties: false
                proxy_execute:
                  type:
                    - object
                    - 'null'
                  properties:
                    enable:
                      type: boolean
                      description: >-
                        When true, the agent can make authenticated HTTP
                        requests to connected app APIs outside the workbench.
                        When false, proxy execution is also disabled inside the
                        workbench, regardless of
                        workbench.enable_proxy_execution. When not set, proxy
                        execute is disabled outside the workbench.
                      example: true
                  required:
                    - enable
                  additionalProperties: false
                preload:
                  type: object
                  properties:
                    tools:
                      anyOf:
                        - type: array
                          items:
                            type: string
                        - type: string
                      description: >-
                        Explicit tool slugs to preload, or "all" to dynamically
                        expose all current and future app tools allowed by the
                        positive session filters. "all" is capped at 1000 tools
                        and is not supported without a positive allowlist.
                      example: all
                  additionalProperties: false
                  description: >-
                    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.
                search:
                  type: object
                  properties:
                    enable:
                      type: boolean
                      default: true
                  additionalProperties: false
                execute:
                  type: object
                  properties:
                    enable_multi_execute:
                      type: boolean
                      default: true
                  additionalProperties: false
                hooks:
                  type:
                    - array
                    - 'null'
                  items:
                    oneOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - before_execute
                          id:
                            type: string
                            pattern: ^[a-z0-9_-]{1,64}$
                            description: >-
                              Unique within the session. Shows up in results and
                              logs.
                          name:
                            type: string
                            minLength: 1
                            maxLength: 120
                            description: >-
                              A readable name. The agent sees it when this hook
                              blocks a call.
                          applies_to:
                            anyOf:
                              - type: string
                                enum:
                                  - all
                              - type: object
                                properties:
                                  toolkits:
                                    type: array
                                    items:
                                      type: string
                                      minLength: 1
                                    minItems: 1
                                    description: Toolkit slugs
                                required:
                                  - toolkits
                                additionalProperties: false
                            description: >-
                              Which tools the hook covers: "all" for all of
                              them, or only the listed toolkits.
                          handler:
                            type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - condition_check
                              condition:
                                type: string
                                minLength: 1
                                maxLength: 2000
                                description: >-
                                  What to block, written as a plain sentence.
                                  For example: "Sending email to anyone outside
                                  example.org".
                              action:
                                type: string
                                enum:
                                  - block
                            required:
                              - type
                              - condition
                              - action
                            additionalProperties: false
                        required:
                          - type
                          - id
                          - applies_to
                          - handler
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - after_execute
                          id:
                            type: string
                            pattern: ^[a-z0-9_-]{1,64}$
                            description: >-
                              Unique within the session. Shows up in results and
                              logs.
                          name:
                            type: string
                            minLength: 1
                            maxLength: 120
                            description: >-
                              A readable name. The agent sees it when this hook
                              blocks a call.
                          applies_to:
                            anyOf:
                              - type: string
                                enum:
                                  - all
                              - type: object
                                properties:
                                  toolkits:
                                    type: array
                                    items:
                                      type: string
                                      minLength: 1
                                    minItems: 1
                                    description: Toolkit slugs
                                required:
                                  - toolkits
                                additionalProperties: false
                            description: >-
                              Which tools the hook covers: "all" for all of
                              them, or only the listed toolkits.
                          handler:
                            oneOf:
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - condition_check
                                  condition:
                                    type: string
                                    minLength: 1
                                    maxLength: 2000
                                    description: >-
                                      What to block, written as a plain
                                      sentence. For example: "Sending email to
                                      anyone outside example.org".
                                  action:
                                    type: string
                                    enum:
                                      - block
                                required:
                                  - type
                                  - condition
                                  - action
                                additionalProperties: false
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - prompt_injection_check
                                  action:
                                    type: string
                                    enum:
                                      - block
                                required:
                                  - type
                                  - action
                                additionalProperties: false
                                description: >-
                                  Blocks a tool response that tries to
                                  manipulate the agent: override its
                                  instructions, change its role, or make it take
                                  actions the user didn't ask for.
                        required:
                          - type
                          - id
                          - applies_to
                          - handler
                        additionalProperties: false
                  maxItems: 20
                  description: >-
                    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.
                experimental:
                  type:
                    - object
                    - 'null'
                  properties:
                    permissions:
                      type: object
                      properties:
                        default:
                          type: string
                          enum:
                            - allow_all
                            - ask_every_call
                            - ask_once_per_session
                          description: >-
                            Default elicitation behavior when no override
                            matches. `allow_all` runs every tool without
                            prompting; `ask_every_call` prompts on each
                            invocation; `ask_once_per_session` prompts once and
                            remembers the answer for the rest of the session.
                        overrides:
                          type: object
                          additionalProperties:
                            type: string
                            enum:
                              - always_allow
                              - always_deny
                              - ask_once
                              - ask_always
                          description: >-
                            Per-tool overrides keyed by
                            `${toolSlug}:${connectedAccountId ?? "__none__"}`,
                            plus account-wide overrides keyed by
                            `*:${connectedAccountId ?? "__none__"}`. Exact tool
                            overrides take precedence over account-wide
                            overrides. `always_allow` skips the prompt and runs
                            the tool; `always_deny` blocks the tool; `ask_once`
                            prompts once per session (allow/deny) and remembers;
                            `ask_always` prompts on every call with
                            allow-once/allow-session/deny, ignoring any cached
                            session allow. Overrides take precedence over
                            `default`.
                      required:
                        - default
                      description: >-
                        Per-tool elicitation permission config. Replaces the
                        stored block when provided.
                    link_url_overwrite:
                      type: string
                      format: uri
                      description: >-
                        Experimental base URL override for connection link
                        redirects created from this tool-router session. When
                        set, link creation returns
                        `${link_url_overwrite}/link/{link_token}` instead of the
                        default Composio Connect base URL. Use only when your
                        integration needs links to open through a custom Connect
                        host.
                      x-experimental: true
                    fast_mode:
                      type: boolean
                      description: >-
                        Fast mode reduces search latency. It is experimental, so
                        tool search quality may be affected.
                      x-experimental: true
                    submit_feedback:
                      type: object
                      properties:
                        enable:
                          type: boolean
                          description: >-
                            Set to true to expose the COMPOSIO_SUBMIT_FEEDBACK
                            helper tool in this session, false to hide it.
                      required:
                        - enable
                      additionalProperties: false
                      description: >-
                        Exposes the COMPOSIO_SUBMIT_FEEDBACK helper tool in this
                        session so the agent can report tool executions with
                        empty, incorrect, or failed results. Replaces the stored
                        block when provided; `enable` is required when the block
                        is sent.
                      x-experimental: true
                    no_elicitation_support_fallback:
                      type: string
                      enum:
                        - deny
                        - allow
                      description: >-
                        What session MCP does with a tool call that needs
                        approval when the MCP client can't ask the user. deny
                        (default) rejects the call; allow runs it without
                        approval.
                      x-experimental: true
                    session_config_id:
                      type: string
                      format: sessionConfigId
                      description: >-
                        Apply the latest active Session config from this project
                        to this Session. Replaces toolkit, tool, and tag access;
                        preserves other settings. Cannot be combined with inline
                        toolkits, tools, or tags. Later config edits do not
                        update this Session automatically.
                      x-experimental: true
                  additionalProperties: false
                  x-experimental: true
              additionalProperties: false
      responses:
        '200':
          description: Session config successfully patched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                    format: toolRouterSessionId
                    description: The identifier of the session
                    example: trs_1a2b3c4d5e6f
                  mcp:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - http
                        description: The type of the MCP server. Can be http
                      url:
                        type: string
                        format: uri
                        description: The URL of the MCP server
                        example: >-
                          https://app.composio.dev/tool_router/v3/trs_1a2b3c4d5e6f/mcp
                    required:
                      - type
                      - url
                  tool_router_tools:
                    type: array
                    items:
                      type: string
                    description: List of available tools in this session
                  config:
                    type: object
                    properties:
                      user_id:
                        type: string
                        description: User identifier for this session
                      toolkits:
                        anyOf:
                          - type: object
                            properties:
                              enabled:
                                type: array
                                items:
                                  type: string
                              require_approval:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  Tool calls matched here pause until the user
                                  approves them.
                                x-experimental: true
                            required:
                              - enabled
                            additionalProperties: false
                          - type: object
                            properties:
                              disabled:
                                type: array
                                items:
                                  type: string
                              require_approval:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  Tool calls matched here pause until the user
                                  approves them.
                                x-experimental: true
                            required:
                              - disabled
                            additionalProperties: false
                          - type: object
                            properties:
                              require_approval:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  Tool calls matched here pause until the user
                                  approves them.
                                x-experimental: true
                            required:
                              - require_approval
                            additionalProperties: false
                        description: >-
                          Toolkit configuration - either enabled list or
                          disabled list, or toolkits whose tools need approval
                      auth_configs:
                        type: object
                        additionalProperties:
                          type: string
                          format: authConfigId
                        description: Auth config overrides per toolkit
                      instant:
                        anyOf:
                          - type: boolean
                            enum:
                              - false
                          - type: object
                            properties:
                              toolkits:
                                anyOf:
                                  - type: object
                                    properties:
                                      enabled:
                                        type: array
                                        items:
                                          type: string
                                    required:
                                      - enabled
                                    additionalProperties: false
                                  - type: object
                                    properties:
                                      disabled:
                                        type: array
                                        items:
                                          type: string
                                    required:
                                      - disabled
                                    additionalProperties: false
                                description: >-
                                  Toolkits eligible for instant usage, as an
                                  enabled or disabled list. If absent, no
                                  additional toolkit restriction applies.
                              tools:
                                type: object
                                additionalProperties:
                                  anyOf:
                                    - type: object
                                      properties:
                                        enabled:
                                          type: array
                                          items:
                                            type: string
                                      required:
                                        - enabled
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        disabled:
                                          type: array
                                          items:
                                            type: string
                                      required:
                                        - disabled
                                      additionalProperties: false
                                description: >-
                                  Per-toolkit enabled or disabled lists that
                                  restrict instant usage. Toolkits absent from
                                  this map have no additional tool restriction.
                              return_instant_charge:
                                type: boolean
                                description: >-
                                  Whether session tool responses return a
                                  top-level instant_charge when a charge is
                                  available. Defaults to false; controls
                                  response visibility only.
                              return_prices_in_search:
                                type: boolean
                                description: >-
                                  Experimental. Whether tool search results show
                                  each instant tool's price, under
                                  instant_account.prices. Defaults to false.
                                x-experimental: true
                            required:
                              - return_instant_charge
                              - return_prices_in_search
                            additionalProperties: false
                        description: >-
                          Instant usage settings. False disables instant usage;
                          an object permits it subject to project permission and
                          session toolkit and tool restrictions.
                      manage_connections:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                            default: true
                            description: >-
                              Whether to enable the connection manager for
                              automatic connection handling
                          callback_url:
                            type: string
                            format: uri
                            description: >-
                              Custom callback URL for connected account auth
                              flows
                          enable_wait_for_connections:
                            type: boolean
                            default: false
                            description: >-
                              Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for
                              polling connection status. Default false. May not
                              work reliably with GPT models.
                          enable_connection_removal:
                            type: boolean
                            default: true
                            description: >-
                              Enable the "remove" action in
                              COMPOSIO_MANAGE_CONNECTIONS. Default true.
                        description: Manage connections configuration
                      tools:
                        type: object
                        additionalProperties:
                          anyOf:
                            - type: object
                              properties:
                                enabled:
                                  type: array
                                  items:
                                    type: string
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - enabled
                              additionalProperties: false
                            - type: object
                              properties:
                                disabled:
                                  type: array
                                  items:
                                    type: string
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - disabled
                              additionalProperties: false
                            - type: object
                              properties:
                                tags:
                                  type: object
                                  properties:
                                    enabled:
                                      type: array
                                      items:
                                        type: string
                                        enum:
                                          - readOnlyHint
                                          - createHint
                                          - updateHint
                                          - destructiveHint
                                          - idempotentHint
                                          - openWorldHint
                                      description: >-
                                        Tags that the tool must have at least
                                        one of
                                    disabled:
                                      type: array
                                      items:
                                        type: string
                                        enum:
                                          - readOnlyHint
                                          - createHint
                                          - updateHint
                                          - destructiveHint
                                          - idempotentHint
                                          - openWorldHint
                                      description: Tags that the tool must NOT have any of
                                    require_approval:
                                      type: array
                                      items:
                                        type: string
                                        enum:
                                          - readOnlyHint
                                          - createHint
                                          - updateHint
                                          - destructiveHint
                                          - idempotentHint
                                          - openWorldHint
                                      description: >-
                                        Tool calls matched here pause until the
                                        user approves them.
                                      x-experimental: true
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - tags
                              additionalProperties: false
                            - type: object
                              properties:
                                require_approval:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    Tool calls matched here pause until the user
                                    approves them.
                                  x-experimental: true
                              required:
                                - require_approval
                              additionalProperties: false
                        description: >-
                          Tool-level configuration per toolkit: tools to enable
                          or disable, or tools that need approval
                      tags:
                        type: object
                        properties:
                          enabled:
                            type: array
                            items:
                              type: string
                              enum:
                                - readOnlyHint
                                - createHint
                                - updateHint
                                - destructiveHint
                                - idempotentHint
                                - openWorldHint
                            description: Tags that the tool must have at least one of
                          disabled:
                            type: array
                            items:
                              type: string
                              enum:
                                - readOnlyHint
                                - createHint
                                - updateHint
                                - destructiveHint
                                - idempotentHint
                                - openWorldHint
                            description: Tags that the tool must NOT have any of
                          require_approval:
                            type: array
                            items:
                              type: string
                              enum:
                                - readOnlyHint
                                - createHint
                                - updateHint
                                - destructiveHint
                                - idempotentHint
                                - openWorldHint
                            description: >-
                              Tool calls matched here pause until the user
                              approves them.
                            x-experimental: true
                        description: >-
                          MCP tool annotation hints for filtering tools with
                          enabled/disabled support, and experimentally the tags
                          whose tools need approval. 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.
                      workbench:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: >-
                              Whether the workbench (code execution sandbox) is
                              enabled. When false, COMPOSIO_REMOTE_WORKBENCH and
                              COMPOSIO_REMOTE_BASH_TOOL are not exposed.
                          tool_execution_enabled:
                            type: boolean
                            description: Whether tool execution is enabled in the workbench
                          proxy_execution_enabled:
                            type: boolean
                            description: >-
                              Whether proxy execution is enabled in the
                              workbench
                          auto_offload_threshold:
                            type: number
                            description: >-
                              Character threshold after which tool execution
                              response are saved to a file in workbench. Default
                              is 20k.
                            exclusiveMinimum: 0
                          sandbox_size:
                            type: string
                            enum:
                              - standard
                              - medium
                              - large
                              - xlarge
                            description: >-
                              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.
                        default:
                          enable: true
                          proxy_execution_enabled: true
                        description: Workbench configuration
                      multi_account:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: >-
                              When true, enables multi-account mode for this
                              session. When not set, falls back to
                              org/project-level configuration.
                          max_accounts_per_toolkit:
                            type: integer
                            description: >-
                              Maximum number of connected accounts allowed per
                              toolkit. Defaults to 5 when multi-account is
                              enabled.
                          require_explicit_selection:
                            type: boolean
                            description: >-
                              When true, require explicit account selection when
                              multiple accounts are connected. When false
                              (default), use the first/default account.
                        description: Multi-account configuration for this session.
                      proxy_execute:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            description: >-
                              When true, enables proxy execute outside the
                              workbench. When false, also disables proxy
                              execution inside the workbench.
                        required:
                          - enable
                        description: >-
                          Proxy execute configuration for this session. Omitted
                          when not set.
                      hooks:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - before_execute
                                id:
                                  type: string
                                  pattern: ^[a-z0-9_-]{1,64}$
                                  description: >-
                                    Unique within the session. Shows up in
                                    results and logs.
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 120
                                  description: >-
                                    A readable name. The agent sees it when this
                                    hook blocks a call.
                                applies_to:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - all
                                    - type: object
                                      properties:
                                        toolkits:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                          minItems: 1
                                          description: Toolkit slugs
                                      required:
                                        - toolkits
                                      additionalProperties: false
                                  description: >-
                                    Which tools the hook covers: "all" for all
                                    of them, or only the listed toolkits.
                                handler:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - condition_check
                                    condition:
                                      type: string
                                      minLength: 1
                                      maxLength: 2000
                                      description: >-
                                        What to block, written as a plain
                                        sentence. For example: "Sending email to
                                        anyone outside example.org".
                                    action:
                                      type: string
                                      enum:
                                        - block
                                  required:
                                    - type
                                    - condition
                                    - action
                                  additionalProperties: false
                              required:
                                - type
                                - id
                                - applies_to
                                - handler
                              additionalProperties: false
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - after_execute
                                id:
                                  type: string
                                  pattern: ^[a-z0-9_-]{1,64}$
                                  description: >-
                                    Unique within the session. Shows up in
                                    results and logs.
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 120
                                  description: >-
                                    A readable name. The agent sees it when this
                                    hook blocks a call.
                                applies_to:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - all
                                    - type: object
                                      properties:
                                        toolkits:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                          minItems: 1
                                          description: Toolkit slugs
                                      required:
                                        - toolkits
                                      additionalProperties: false
                                  description: >-
                                    Which tools the hook covers: "all" for all
                                    of them, or only the listed toolkits.
                                handler:
                                  oneOf:
                                    - type: object
                                      properties:
                                        type:
                                          type: string
                                          enum:
                                            - condition_check
                                        condition:
                                          type: string
                                          minLength: 1
                                          maxLength: 2000
                                          description: >-
                                            What to block, written as a plain
                                            sentence. For example: "Sending email to
                                            anyone outside example.org".
                                        action:
                                          type: string
                                          enum:
                                            - block
                                      required:
                                        - type
                                        - condition
                                        - action
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        type:
                                          type: string
                                          enum:
                                            - prompt_injection_check
                                        action:
                                          type: string
                                          enum:
                                            - block
                                      required:
                                        - type
                                        - action
                                      additionalProperties: false
                                      description: >-
                                        Blocks a tool response that tries to
                                        manipulate the agent: override its
                                        instructions, change its role, or make
                                        it take actions the user didn't ask for.
                              required:
                                - type
                                - id
                                - applies_to
                                - handler
                              additionalProperties: false
                        maxItems: 20
                        description: Hooks that run on this session's tool calls.
                      preload:
                        type: object
                        properties:
                          tools:
                            anyOf:
                              - type: array
                                items:
                                  type: string
                              - type: string
                                enum:
                                  - all
                            description: >-
                              Explicit preloaded tool slugs, or "all" when the
                              session dynamically exposes all app tools allowed
                              by its filters.
                        required:
                          - tools
                        additionalProperties: false
                        description: >-
                          Preload configuration. Explicit slugs are returned as
                          an array; dynamic preload is returned as "all".
                      connected_accounts:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                            format: connectedAccountId
                          minItems: 1
                        description: >-
                          Per-toolkit connected account overrides (array of
                          nano-IDs). Multi-account sessions can pin more than
                          one account per toolkit; otherwise length is 1.
                      search:
                        type: object
                        properties:
                          enable:
                            type: boolean
                            default: true
                        description: Search helper configuration
                      execute:
                        type: object
                        properties:
                          enable_multi_execute:
                            type: boolean
                            default: true
                        description: Execute helper configuration
                    required:
                      - user_id
                      - instant
                      - preload
                      - search
                      - execute
                    description: The configuration used to create this session
                  config_version:
                    type: integer
                    description: >-
                      Monotonic version of the config. Incremented on each
                      PATCH. Use for optimistic concurrency control.
                  experimental:
                    type: object
                    properties:
                      assistive_prompt:
                        type: string
                        description: >-
                          The assistive system prompt for the tool router
                          session
                      custom_toolkits:
                        type: array
                        items:
                          type: object
                          properties:
                            slug:
                              type: string
                              minLength: 1
                              pattern: ^[a-zA-Z0-9_-]+$
                            name:
                              type: string
                              minLength: 1
                              maxLength: 128
                            description:
                              type: string
                              minLength: 1
                              maxLength: 2048
                            tools:
                              type: array
                              items:
                                type: object
                                properties:
                                  slug:
                                    type: string
                                    description: >-
                                      Prefixed tool slug (e.g.
                                      LOCAL_CRM_FIND_CUSTOMER)
                                  name:
                                    type: string
                                    minLength: 1
                                    maxLength: 128
                                  description:
                                    type: string
                                    minLength: 1
                                    maxLength: 5120
                                  input_schema:
                                    type: object
                                    additionalProperties: {}
                                  output_schema:
                                    type: object
                                    additionalProperties: {}
                                  original_slug:
                                    type: string
                                    description: Original tool slug as provided by the user
                                  preload:
                                    type: boolean
                                    description: >-
                                      Echoes the SDK-local preload hint provided
                                      for this tool
                                required:
                                  - slug
                                  - name
                                  - description
                                  - input_schema
                                  - original_slug
                            preload:
                              type: boolean
                              description: >-
                                Echoes the SDK-local preload hint provided for
                                this toolkit
                          required:
                            - slug
                            - name
                            - description
                            - tools
                        description: >-
                          User-defined custom toolkits with grouped tools
                          (no-auth)
                      custom_tools:
                        type: array
                        items:
                          type: object
                          properties:
                            slug:
                              type: string
                              description: >-
                                Prefixed tool slug (e.g.
                                LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
                            name:
                              type: string
                              minLength: 1
                              maxLength: 128
                            description:
                              type: string
                              minLength: 1
                              maxLength: 5120
                            input_schema:
                              type: object
                              additionalProperties: {}
                            output_schema:
                              type: object
                              additionalProperties: {}
                            extends_toolkit:
                              type: string
                              minLength: 1
                            original_slug:
                              type: string
                              description: Original tool slug as provided by the user
                            preload:
                              type: boolean
                              description: >-
                                Echoes the SDK-local preload hint provided for
                                this tool
                          required:
                            - slug
                            - name
                            - description
                            - input_schema
                            - original_slug
                        description: >-
                          Custom tools — standalone or extending Composio
                          toolkits
                      no_elicitation_support_fallback:
                        type: string
                        enum:
                          - deny
                          - allow
                        description: >-
                          What session MCP does with a tool call that needs
                          approval when the MCP client can't ask the user.
                          Omitted when not set, which means deny.
                        x-experimental: true
                      source_session_config:
                        type: object
                        properties:
                          id:
                            type: string
                            format: sessionConfigId
                        required:
                          - id
                        description: >-
                          Experimental provenance for the reusable Session
                          config most recently applied to this Session.
                        x-experimental: true
                    description: Experimental v3.1 features
                    x-experimental: true
                  warnings:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          enum:
                            - PRELOAD_TOOLS_HIGH_CONTEXT_USAGE
                          description: >-
                            Stable machine code identifying the advisory. Safe
                            to switch on in client code.
                          example: PRELOAD_TOOLS_HIGH_CONTEXT_USAGE
                        message:
                          type: string
                          description: >-
                            Human-readable description of the advisory. Suitable
                            for logging or surfacing to end users.
                          example: >-
                            Session preloads 25 tools; each preloaded tool adds
                            to the agent context window. Consider keeping the
                            list at or under ~20 tools.
                      required:
                        - code
                        - message
                    default: []
                    description: >-
                      Advisory list — the session exists and is usable, but the
                      listed issues may warrant attention.
                    example:
                      - 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.
                required:
                  - session_id
                  - mcp
                  - tool_router_tools
                  - config
                  - config_version
        '400':
          description: Bad request. Invalid config values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Session configs are not enabled for this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session or active Session config not found in this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '408':
          description: Request timeout while validating patch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Config version conflict. Re-fetch the session and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded while validating the patch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key

````