# Create a new tool router session

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

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.

---

## POST `/api/v3/tool_router/session`

**Endpoint:** `https://backend.composio.dev/api/v3/tool_router/session`

**Summary:** 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.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key`

### Request Body

**Schema:**

- `user_id` (string) *(required)*: The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address
- `toolkits` (any): Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive.
- `auth_configs` (object): 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
- `connected_accounts` (object): The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed
- `manage_connections` (object): Configuration for connection management settings
  - `enable` (boolean,null): 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.
  - `callback_url` (string (uri)): 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.
  - `enable_wait_for_connections` (boolean,null): 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.
- `tools` (object): Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit
- `tags` (any): 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.
- `workbench` (object): Configuration for workbench behavior
  - `enable_proxy_execution` (boolean): Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.
  - `auto_offload_threshold` (number): 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.
- `experimental` (object): Experimental features - not stable, may be modified or removed in future versions.
  - `assistive_prompt_config` (object): Customize assistive prompt generation (e.g., timezone).
    - `user_timezone` (string): IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.

**Example:**

```json
{
  "user_id": "string",
  "toolkits": null,
  "auth_configs": {},
  "connected_accounts": {},
  "manage_connections": {
    "enable": true,
    "enable_wait_for_connections": false
  },
  "tools": {},
  "tags": null,
  "workbench": {
    "enable_proxy_execution": true
  },
  "experimental": {
    "assistive_prompt_config": {
      "user_timezone": "string"
    }
  }
}
```

### Responses

#### 201 - Session successfully created. Returns the session ID and MCP server URL for the created session.

**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 session configuration including user, toolkits, and overrides
  - `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
  - `connected_accounts` (object): Connected account 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.
  - `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` (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
    - `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.
- `experimental` (object): Experimental features including the generated system prompt. Only returned on session creation, not on GET.
  - `assistive_prompt` (string) *(required)*: The assistive system prompt to inject into your agent for optimal tool router usage

**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": {},
    "connected_accounts": {},
    "manage_connections": {
      "enabled": true,
      "callback_url": "https://example.com",
      "enable_wait_for_connections": false
    },
    "tools": {},
    "tags": {
      "enabled": [
        "..."
      ],
      "disabled": [
        "..."
      ]
    },
    "workbench": {
      "proxy_execution_enabled": true
    }
  },
  "experimental": {
    "assistive_prompt": "string"
  }
}
```

#### 400 - Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.

**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. Authentication is required or the provided credentials are invalid.

**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. The user is not authorized to create a tool router session.

**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. An unexpected error occurred while processing the request.

**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/tool_router/session" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "string",
    "toolkits": null,
    "auth_configs": {},
    "connected_accounts": {},
    "manage_connections": {
      "enable": true,
      "enable_wait_for_connections": false
    },
    "tools": {},
    "tags": null,
    "workbench": {
      "enable_proxy_execution": true
    },
    "experimental": {
      "assistive_prompt_config": {
        "user_timezone": "string"
      }
    }
  }'
```