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

# Create a new tool router session

> Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v3.1/tool_router/session
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:
    post:
      tags:
        - Tool Router
      summary: Create a new tool router session
      description: >-
        Creates a new session for the tool router feature. This endpoint
        initializes a new session with specified toolkits and their
        authentication configurations. The session provides an isolated
        environment for testing and managing tool routing logic with scoped MCP
        server access.
      operationId: postToolRouterSession
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  minLength: 1
                  description: >-
                    The identifier of the user who is initiating the session,
                    ideally a unique identifier from your database like a user
                    ID or email address
                  example: user_123456789
                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
                  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
                  properties:
                    enable:
                      type:
                        - boolean
                        - 'null'
                      default: true
                      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'
                      default: false
                      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'
                      default: true
                      description: >-
                        Enable the "remove" action in
                        COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected
                        accounts. Default true.
                  default:
                    enable: true
                    enable_wait_for_connections: false
                    enable_connection_removal: true
                  additionalProperties: false
                  description: Configuration for connection management settings
                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
                  properties:
                    enable:
                      type: boolean
                      default: true
                      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
                      default: true
                      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.
                    enable_proxy_execution:
                      type: boolean
                      default: true
                      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
                      default: standard
                      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.
                      example: standard
                  default:
                    enable: true
                  additionalProperties: false
                  description: Configuration for workbench behavior
                proxy_execute:
                  type: object
                  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
                  description: >-
                    Configure proxy execute. Omitted from responses when not
                    set. Session creation fails when enable is false and
                    workbench.enable_proxy_execution is explicitly true.
                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.
                      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
                  description: >-
                    Configure multi-account behavior. When enabled, users can
                    connect multiple accounts per toolkit.
                experimental:
                  type: object
                  properties:
                    assistive_prompt_config:
                      type: object
                      properties:
                        user_timezone:
                          type: string
                          description: >-
                            IANA timezone identifier (e.g., 'America/New_York',
                            'Europe/London'). Used to customize the system
                            prompt with timezone-aware instructions.
                          example: America/New_York
                      additionalProperties: false
                      description: Customize assistive prompt generation (e.g., timezone).
                    custom_toolkits:
                      type: array
                      items:
                        type: object
                        properties:
                          slug:
                            type: string
                            minLength: 1
                            pattern: ^[a-zA-Z0-9_-]+$
                            description: >-
                              Unique slug for the toolkit. Must not conflict
                              with existing Composio toolkit slugs.
                              Alphanumeric, underscores, and hyphens only.
                            example: ecommerce
                          name:
                            type: string
                            minLength: 1
                            maxLength: 128
                            description: >-
                              Display name shown to the LLM and in search
                              results.
                            example: E-Commerce API
                          description:
                            type: string
                            minLength: 1
                            maxLength: 2048
                            description: >-
                              Used for BM25 search matching and shown in toolkit
                              connection statuses.
                            example: >-
                              Internal e-commerce API for order management and
                              fulfillment
                          preload:
                            type: boolean
                            description: >-
                              SDK hint for direct custom-tool exposure. Not
                              stored in session config; echoed in create/attach
                              responses for inline custom definitions.
                          tools:
                            type: array
                            items:
                              type: object
                              properties:
                                slug:
                                  type: string
                                  minLength: 1
                                  pattern: ^[a-zA-Z0-9_-]+$
                                  description: >-
                                    Tool slug. Combined with toolkit slug to
                                    form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars
                                    total).
                                  example: GET_CUSTOMER_ORDERS
                                name:
                                  type: string
                                  minLength: 1
                                  maxLength: 128
                                  description: Human-readable display name
                                  example: Get Customer Orders
                                description:
                                  type: string
                                  minLength: 1
                                  maxLength: 5120
                                  description: >-
                                    Used for BM25 search matching and shown to
                                    the LLM.
                                  example: >-
                                    Fetch recent orders for a customer by their
                                    email address
                                input_schema:
                                  type: object
                                  additionalProperties: {}
                                  description: >-
                                    Must have type: "object" and a properties
                                    field.
                                  example:
                                    type: object
                                    properties:
                                      email:
                                        type: string
                                        description: Customer email
                                    required:
                                      - email
                                output_schema:
                                  type: object
                                  additionalProperties: {}
                                  description: >-
                                    Optional output schema for the tool
                                    response.
                                preload:
                                  type: boolean
                                  description: >-
                                    SDK hint for direct custom-tool exposure.
                                    Not stored in session config; echoed in
                                    create/attach responses for inline custom
                                    definitions.
                              required:
                                - slug
                                - name
                                - description
                                - input_schema
                            minItems: 1
                            maxItems: 100
                            description: Tools in this custom toolkit
                        required:
                          - slug
                          - name
                          - description
                          - tools
                      description: >-
                        Custom toolkits with grouped tools. Toolkit slugs must
                        not conflict with existing Composio toolkits. All tools
                        are no-auth.
                    custom_tools:
                      type: array
                      items:
                        type: object
                        properties:
                          slug:
                            type: string
                            minLength: 1
                            pattern: ^[a-zA-Z0-9_-]+$
                            description: >-
                              Tool slug. Forms LOCAL_<TOOL> (standalone) or
                              LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars
                              total.
                            example: GET_IMPORTANT_EMAILS
                          name:
                            type: string
                            minLength: 1
                            maxLength: 128
                            description: Human-readable display name
                            example: Get Important Emails
                          description:
                            type: string
                            minLength: 1
                            maxLength: 5120
                            description: >-
                              Used for BM25 search matching and shown to the
                              LLM.
                            example: >-
                              Fetch emails marked as important from the last 24
                              hours
                          input_schema:
                            type: object
                            additionalProperties: {}
                            description: 'Must have type: "object" and a properties field.'
                            example:
                              type: object
                              properties:
                                limit:
                                  type: number
                                  description: Max results to return
                          output_schema:
                            type: object
                            additionalProperties: {}
                            description: JSON Schema describing tool output (optional)
                          extends_toolkit:
                            type: string
                            minLength: 1
                            description: >-
                              If set, must be a valid Composio toolkit slug. The
                              tool inherits that toolkit's auth/connection
                              status. If omitted, the tool is standalone
                              (no-auth).
                            example: gmail
                          preload:
                            type: boolean
                            description: >-
                              SDK hint for direct custom-tool exposure. Not
                              stored in session config; echoed in create/attach
                              responses for inline custom definitions.
                        required:
                          - slug
                          - name
                          - description
                          - input_schema
                      description: >-
                        Custom tools to include in search. Standalone tools need
                        no auth. Tools with extends_toolkit inherit the Composio
                        toolkit's connection.
                    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. Default behavior
                        + per-tool always_allow/always_deny overrides. Mutation
                        via PATCH.
                    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
                          default: false
                          description: >-
                            Set to true to expose the COMPOSIO_SUBMIT_FEEDBACK
                            helper tool in this session. Defaults to false.
                      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. Defaults to false.
                      x-experimental: true
                    restrict_egress_to_composio:
                      type: boolean
                      default: false
                      description: >-
                        Set to true to confine the workbench sandbox to
                        Composio: code running in it can reach the Composio API
                        and its own storage volume, and no other network
                        destination. Defaults to false. Set at session creation
                        only.
                      x-experimental: true
                    no_elicitation_support_fallback:
                      type: string
                      enum:
                        - deny
                        - allow
                      default: deny
                      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: >-
                        Experimental reusable Session config to resolve for this
                        new Session. Mutually exclusive with inline toolkit and
                        tool access fields; authentication and runtime fields
                        remain per Session.
                      x-experimental: true
                  x-experimental: true
                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.
                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. A hook can
                    block a call before it runs, or block its result before the
                    agent sees it.
                search:
                  type: object
                  properties:
                    enable:
                      type: boolean
                      default: true
                  default:
                    enable: true
                  additionalProperties: false
                execute:
                  type: object
                  properties:
                    enable_multi_execute:
                      type: boolean
                      default: true
                  default:
                    enable_multi_execute: true
                  additionalProperties: false
              required:
                - user_id
            examples:
              Session with all toolkits:
                value:
                  user_id: user_123456789
              Session with only specific toolkits:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                      - slack
              Session with only specific toolkits disabled:
                value:
                  user_id: user_123456789
                  toolkits:
                    disable:
                      - gmail
                      - slack
              Session with connection manager enabled:
                value:
                  user_id: user_123456789
                  manage_connections:
                    enable: true
              Session with connection manager and specific toolkits:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                      - slack
                  manage_connections:
                    enable: true
              Session with custom callback URL:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - github
                      - slack
                  manage_connections:
                    enable: true
                    callback_url: https://your-app.com/auth/callback
              Session with workbench configuration:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                  workbench:
                    enable_proxy_execution: true
                    auto_offload_threshold: 10000
              Session with global tags filter:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                      - slack
                  tags:
                    - readOnlyHint
                    - idempotentHint
              Session with auth config overrides:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                      - slack
                  auth_configs:
                    gmail: ac_1a2b3c4d5e6f
                    slack: ac_7g8h9i0j1k2l
              Session with connected account overrides:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                      - slack
                  connected_accounts:
                    gmail: ca_1a2b3c4d5e6f
                    slack: ca_7g8h9i0j1k2l
              Session with comprehensive configuration:
                value:
                  user_id: user_123456789
                  toolkits:
                    enable:
                      - gmail
                      - slack
                      - github
                  auth_configs:
                    gmail: ac_1a2b3c4d5e6f
                    slack: ac_7g8h9i0j1k2l
                  connected_accounts:
                    github: ca_3m4n5o6p7q8r
                  manage_connections:
                    enable: true
                    callback_url: https://your-app.com/auth/callback
                  tools:
                    gmail:
                      enable:
                        - GMAIL_SEND_EMAIL
                        - GMAIL_FETCH_EMAILS
                    slack:
                      disable:
                        - SLACK_ADD_EMOJI
                    slackbot:
                      tags:
                        - destructiveHint
                  tags:
                    - destructiveHint
                    - idempotentHint
                  workbench:
                    enable_proxy_execution: true
                    auto_offload_threshold: 10000
              Session with disabled toolkits and global tags:
                value:
                  user_id: user_123456789
                  toolkits:
                    disable:
                      - gmail
                  tags:
                    - readOnlyHint
      responses:
        '201':
          description: >-
            Session successfully created. Returns the session ID and MCP server
            URL for the created session.
          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 - may change without notice
                    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. This may occur if the user_id format is invalid,
            toolkit names are invalid, or auth_config_id IDs are malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized. Authentication is required or the provided credentials
            are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Forbidden. The user is not authorized to create a tool router
            session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Not found. The referenced Session config or another requested
            resource does not exist in this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '408':
          description: Request timeout. The session creation took too long to complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too many requests. The upstream service is rate limiting the
            request; retry after a short backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            Internal server error. An unexpected error occurred while processing
            the request.
          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

````