---
title: "Attach to an existing tool router session (v3.1)"
method: POST
path: "/api/v3.1/tool_router/session/{session_id}/attach"
tags: ["Tool Router"]
---

# Attach to an existing tool router session (v3.1)

`POST /api/v3.1/tool_router/session/{session_id}/attach`

Fetch an existing tool router session by ID.

## Path parameters

- `session_id` string, toolRouterSessionId, required — The unique identifier of the tool router session

## Request body

- object
  - `experimental` object — Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them.
    - `custom_toolkits` object[] — Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth.
      - `slug` string, required — Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.
      - `name` string, required — Display name shown to the LLM and in search results.
      - `description` string, required — Used for BM25 search matching and shown in toolkit connection statuses.
      - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.
      - `tools` object[], required — Tools in this custom toolkit
        - `slug` string, required — Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).
        - `name` string, required — Human-readable display name
        - `description` string, required — Used for BM25 search matching and shown to the LLM.
        - `input_schema` object, required — Must have type: "object" and a properties field.
        - `output_schema` object — Optional output schema for the tool response.
        - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.
    - `custom_tools` object[] — Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection.
      - `slug` string, required — Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.
      - `name` string, required — Human-readable display name
      - `description` string, required — Used for BM25 search matching and shown to the LLM.
      - `input_schema` object, required — Must have type: "object" and a properties field.
      - `output_schema` object — JSON Schema describing tool output (optional)
      - `extends_toolkit` string — 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).
      - `preload` boolean — SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions.

## Response `200`

Session successfully attached. Returns the session payload.

- object
  - `session_id` string, toolRouterSessionId, required — The identifier of the session
  - `mcp` object, required
    - `type` 'http', required — The type of the MCP server. Can be http
    - `url` string, uri, required — The URL of the MCP server
  - `tool_router_tools` string[], required — List of available tools in this session
  - `config` object, required — The configuration used to create this session
    - `user_id` string, required — User identifier for this session
    - `toolkits` union — Toolkit configuration - either enabled list or disabled list
      - object
        - `enabled` string[], required
      - object
        - `disabled` string[], required
    - `auth_configs` object — Auth config overrides per toolkit
    - `manage_connections` object — Manage connections configuration
      - `enabled` boolean — Whether to enable the connection manager for automatic connection handling
      - `callback_url` string, uri — Custom callback URL for connected account auth flows
      - `enable_wait_for_connections` boolean — Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models.
      - `enable_connection_removal` boolean — Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS. Default true.
    - `tools` object — Tool-level configuration per toolkit
    - `tags` object — MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied.
      - `enabled` string[] — Tags that the tool must have at least one of
      - `disabled` string[] — Tags that the tool must NOT have any of
    - `workbench` object — Workbench configuration
      - `enable` boolean — Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
      - `proxy_execution_enabled` boolean — Whether proxy execution is enabled in the workbench
      - `auto_offload_threshold` number — Character threshold after which tool execution response are saved to a file in workbench. Default is 20k.
      - `sandbox_size` 'standard' | 'medium' | 'large' | 'xlarge' — Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
    - `multi_account` object — Multi-account configuration for this session.
      - `enable` boolean — When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.
      - `max_accounts_per_toolkit` integer — Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled.
      - `require_explicit_selection` boolean — When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account.
    - `preload` object, required — Preload configuration. Explicit slugs are returned as an array; dynamic preload is returned as "all".
      - `tools` union, required — Explicit preloaded tool slugs, or "all" when the session dynamically exposes all app tools allowed by its filters.
        - string[]
        - 'all'
    - `connected_accounts` object — 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` object, required — Search helper configuration
      - `enable` boolean
    - `execute` object, required — Execute helper configuration
      - `enable_multi_execute` boolean
  - `config_version` integer, required — Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control.
  - `experimental` object — Experimental features
    - `assistive_prompt` string — The assistive system prompt for the tool router session
    - `custom_toolkits` object[] — User-defined custom toolkits with grouped tools (no-auth)
      - `slug` string, required
      - `name` string, required
      - `description` string, required
      - `tools` object[], required
        - `slug` string, required — Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)
        - `name` string, required
        - `description` string, required
        - `input_schema` object, required
        - `output_schema` object
        - `original_slug` string, required — Original tool slug as provided by the user
    - `custom_tools` object[] — Custom tools — standalone or extending Composio toolkits
      - `slug` string, required — Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
      - `name` string, required
      - `description` string, required
      - `input_schema` object, required
      - `output_schema` object
      - `extends_toolkit` string
      - `original_slug` string, required — Original tool slug as provided by the user
  - `warnings` object[] — Advisory list — the session exists and is usable, but the listed issues may warrant attention.
    - `code` 'PRELOAD_TOOLS_HIGH_CONTEXT_USAGE', required — Stable machine code identifying the advisory. Safe to switch on in client code.
    - `message` string, required — Human-readable description of the advisory. Suitable for logging or surfacing to end users.

## Other responses

- `400` — Bad request. Custom tool validation failed (slug collision, invalid extends_toolkit, schema invalid, etc).
- `401` — Unauthorized.
- `404` — Session not found or has been deleted.
- `500` — Internal server error.

---

[API](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/versions/4239836857f8/schema)