Composio Tool Router API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Tool Router API
  description: (Labs) Tool router endpoints
  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: PRODUCTION API
tags:
- name: Tool Router
  description: (Labs) Tool router endpoints
paths:
  /api/v3/labs/tool_router/session:
    post:
      summary: Create a new tool router session (Legacy)
      description: Creates a new session for the tool router lab feature (Legacy). 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.
      tags:
      - Tool Router
      operationId: postLabsToolRouterSession
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: Unique user identifier for the session owner
                  example: user_123456789
                config:
                  type: object
                  properties:
                    manually_manage_connections:
                      type: boolean
                      nullable: true
                      default: false
                      description: Whether to manually manage connections
                      example: true
                    toolkits:
                      type: array
                      items:
                        type: object
                        properties:
                          toolkit:
                            type: string
                            minLength: 1
                            description: Toolkit identifier (e.g., gmail, slack, github)
                            example: gmail
                          auth_config_id:
                            type: string
                            description: Specific auth configuration ID for this toolkit
                            example: ac_1a2b3c4d5e6f
                        required:
                        - toolkit
                      default: []
                      description: Array of toolkit configurations with optional auth configs
                      example:
                      - toolkit: gmail
                        auth_config_id: ac_1a2b3c4d5e6f
                      - toolkit: slack
                  default: {}
                  description: Session configuration including enabled toolkits and their auth configs
                  example:
                    manually_manage_connections: false
                    toolkits:
                    - toolkit: gmail
                      auth_config_id: ac_1a2b3c4d5e6f
                    - toolkit: slack
              required:
              - user_id
            examples:
              Session with multiple toolkits:
                value:
                  user_id: user_123456789
                  config:
                    toolkits:
                    - toolkit: gmail
                      auth_config_id: ac_1a2b3c4d5e6f
                    - toolkit: slack
                      auth_config_id: ac_7g8h9i0j1k2l
                    - toolkit: github
              Minimal session:
                value:
                  user_id: user_123456789
                  config: {}
              Session with single toolkit:
                value:
                  user_id: user_123456789
                  config:
                    toolkits:
                    - toolkit: gmail
      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
                    description: Generated session identifier (prefixed with "trs_")
                    example: trs_1a2b3c4d5e6f
                  chat_session_mcp_url:
                    type: string
                    format: uri
                    description: MCP server endpoint URL for this specific chat session
                    example: https://api.composio.dev/v3/mcp/tool-router/trs_1a2b3c4d5e6f/mcp
                  tool_router_instance_mcp_url:
                    type: string
                    format: uri
                    description: MCP server endpoint URL for this specific tool router instance
                    example: https://api.composio.dev/v3/mcp/tool-router/trs_1a2b3c4d5e6f/mcp
                required:
                - session_id
                - chat_session_mcp_url
                - tool_router_instance_mcp_url
        '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'
        '409':
          description: Conflict. A session for this user with the same configuration already exists.
          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'
  /api/v3/tool_router/session:
    post:
      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.
      tags:
      - Tool Router
      operationId: postToolRouterSession
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      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
                    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.
                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
                  description: Per-toolkit connected account override (single nano-ID). Each connected account must exist (not deleted or disabled) and belong to the same `user_id` as the session.
                  additionalProperties:
                    type: string
                    example: ca_3m4n5o6p7q8r
                  example:
                    github: ca_3m4n5o6p7q8r
                manage_connections:
                  type: object
                  properties:
                    enable:
                      type: boolean
                      nullable: true
                      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
                      nullable: true
                      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
                      nullable: true
                      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
                      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
                    - type: object
                      properties:
                        tags:
                          anyOf:
                          - type: array
                            items:
                              type: string
                              enum:
                              - readOnlyHint
                              - destructiveHint
                              - idempotentHint
                              - openWorldHint
                          - type: object
                            properties:
                              enable:
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - readOnlyHint
                                  - destructiveHint
                                  - idempotentHint
                                  - openWorldHint
                              disable:
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - readOnlyHint
                                  - destructiveHint
                                  - idempotentHint
                                  - openWorldHint
                          description: MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.
                          example:
                            enable:
                            - openWorldHint
                            disable:
                            - destructiveHint
                      required:
                      - tags
                      additionalProperties: false
                  description: Tool-level configuration per toolkit. Allows you to enable, disable, or filter by tags for specific tools within each toolkit. Every slug passed in `enable` / `disable` must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.
                  example:
                    gmail:
                      enable:
                      - GMAIL_SEND_EMAIL
                      - GMAIL_FETCH_EMAILS
                    slack:
                      disable:
                      - SLACK_ADD_EMOJI
                    slackbot:
                      tags:
                        enable:
                        - destructiveHint
                        disable:
                        - openWorldHint
                tags:
                  anyOf:
                  - type: array
                    items:
                      type: string
                      enum:
                      - readOnlyHint
                      - destructiveHint
                      - idempotentHint
                      - openWorldHint
                  - type: object
                    properties:
                      enable:
                        type: array
                        items:
                          type: string
                          enum:
                          - readOnlyHint
                          - destructiveHint
                          - idempotentHint
                          - openWorldHint
                      disable:
                        type: array
                        items:
                          type: string
                          enum:
                          - readOnlyHint
                          - destructiveHint
                          - idempotentHint
                          - openWorldHint
                  description: Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.
                  example:
                    enable:
                    - openWorldHint
                    disable:
                    - 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_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
                      minimum: 0
                      exclusiveMinimum: true
                      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
                    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
                    enable_proxy_execution: true
                  additionalProperties: false
                  description: Configuration for workbench behavior
                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:
                                    nullable: true
                                  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:
                                    nullable: true
                                  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:
                              nullable: true
                            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:
                              nullable: true
                            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
                  description: Experimental features - not stable, may be modified or removed in future versions.
                  x-experimental: true
                preload:
                  type: object
                  properties:
                    tools:
                      type: array
                      items:
                        type: string
                      description: Composio tool slugs to preload. Each slug must be allowed by the session filters (`toolkits`, `tools`, `tags`) — unknown, blocked, meta, or custom slugs return a 400 at session creation.
                      example:
                      - GMAIL_FETCH_EMAILS
                      - SLACK_SEND_MESSAGE
                  additionalProperties: false
                  description: Preload configuration for Composio tools. Controls which tools appear in `session.tools` and the MCP server tool list so the agent can call them directly without going through search first. Custom tools use `preload` on the custom tool/toolkit definition instead. Not supported when multi-account is enabled. Each preloaded tool adds to the agent context window, so keep the list at or under ~20 tools.
              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.

# --- truncated at 32 KB (216 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/composio/refs/heads/main/openapi/composio-tool-router-api-openapi.yml