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

**Documentation:** /reference/api-reference/tool-router/postToolRouterSessionBySessionIdAttach

Fetch an existing tool router session by ID.

---

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

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

**Summary:** Attach to an existing tool router session (v3.1)

Fetch an existing tool router session by ID.

### Authentication

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

### Path Parameters

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

### Request Body

**Schema:**

- `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` (array<object>): Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth.
    - Array items:
      - `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` (array<object>) *(required)*: Tools in this custom toolkit
        - Array items:
          - ...
  - `custom_tools` (array<object>): Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection.
    - Array items:
      - `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.
        - `[key: string]` (any)
      - `output_schema` (object): JSON Schema describing tool output (optional)
        - `[key: string]` (any)
      - `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.

**Example:**

```json
{
  "experimental": {
    "custom_toolkits": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "preload": "...",
        "tools": "..."
      }
    ],
    "custom_tools": [
      {
        "slug": "...",
        "name": "...",
        "description": "...",
        "input_schema": "...",
        "output_schema": "...",
        "extends_toolkit": "...",
        "preload": "..."
      }
    ]
  }
}
```

### Responses

#### 200 - Session successfully attached. Returns the session payload.

**Response Schema:**

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

**Example Response:**

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

#### 400 - Bad request. Custom tool validation failed (slug collision, invalid extends_toolkit, schema invalid, etc).

**Response Schema:**

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

#### 401 - Unauthorized.

**Response Schema:**

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

#### 403 - Forbidden. Tool Router V2 is not enabled for your account.

**Response Schema:**

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

#### 404 - Session not found or has been deleted.

**Response Schema:**

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

#### 500 - Internal server error.

**Response Schema:**

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

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3.1/tool_router/session/string/attach" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "experimental": {
      "custom_toolkits": [
        {
          "slug": "...",
          "name": "...",
          "description": "...",
          "preload": "...",
          "tools": "..."
        }
      ],
      "custom_tools": [
        {
          "slug": "...",
          "name": "...",
          "description": "...",
          "input_schema": "...",
          "output_schema": "...",
          "extends_toolkit": "...",
          "preload": "..."
        }
      ]
    }
  }'
```