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

# Configuring Sessions

> Enable toolkits, set auth configs, and select connected accounts

## Creating a session

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(user_id="user_123")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123"}'
> ```

By default, a session has access to every toolkit in the Composio catalog. Your agent can discover and use any of them through `COMPOSIO_SEARCH_TOOLS`. Use the options below to restrict or customize what's available.

You can also attach local custom tools and custom toolkits that run in-process alongside Composio tools. See [Custom tools and toolkits](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md).

> [!WARNING]
>
> Both SDKs pass product and runtime identity through the API client's `identity` option. If you configure custom default or request headers, remove identity headers such as `x-source`, `x-framework`, `x-sdk-version`, and `x-client-*`. The client rejects attempts to override them.

### API key permissions

If you use a [scoped project API key](https://composio-preview.mintlify.site/reference/authenticating-to-composio/project-api-key-permissions.md), grant permissions for the session operations your application needs:

* **Session management** controls creating, viewing, configuring, and deleting sessions. It does not grant tool execution access.
* **Session tool execution** covers search, tool execution, proxy execution, and session-linked MCP access.

Enable both permissions if your application manages sessions and executes tools through them.

## Using a saved Session config

To start a session from a saved access policy you build in the Composio Dashboard, see [Using saved session configs](https://composio-preview.mintlify.site/docs/session-configs.md).

## Reading and updating session configuration

In TypeScript, `session.config` exposes the configuration returned by the server. Call `session.update()` to change selected fields. It preserves omitted fields, updates `session.config` in place, and returns the updated configuration. See [Updating a session](https://composio-preview.mintlify.site/docs/how-composio-works.md#how-sessions-behave) for an example.

`ToolRouterSessionConfig` and `ToolRouterSessionConfigHistoryConfig` use the API client's types. The SDK returns the config as sent by the API, without validating `instant` at runtime or removing `premium_usage`. `instant` is always present as `false` or a policy object. Use `ToolRouterSessionConfig['instant']` when you need its TypeScript type.

When inspecting a returned config, handle `toolkits` and individual `tools` entries that contain only `require_approval`, without `enabled` or `disabled`. `tags` can also carry `require_approval`, and the config can include `proxy_execute`. These fields also appear in configurations returned by `session.listConfigHistory()`.

In Python, `session.config.instant` is a model when it contains a policy. Read its fields with attribute access rather than dictionary indexing, just as you do for [Instant charges](https://composio-preview.mintlify.site/docs/instant-tools.md#return-the-charge-with-a-call).

> [!NOTE]
>
> If you implement the TypeScript `Session` interface yourself, include the required `config` member. Sessions created by the SDK provide it automatically.

## Requiring tool approval

Require approval before selected session tools run by adding `requireApproval` (`require_approval` in Python) to toolkit, tool, or tag filters. These approval settings are experimental.

| Scope | TypeScript session option | Python session option |
| - | - | - |
| All tools in a toolkit | `toolkits: { requireApproval: ["gmail"] }` | `toolkits={"require_approval": ["gmail"]}` |
| Specific tools in a toolkit | `tools: { gmail: { requireApproval: ["GMAIL_SEND_EMAIL"] } }` | `tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}}` |
| Tools with matching tags | `tags: { requireApproval: ["destructiveHint"] }` | `tags={"require_approval": ["destructiveHint"]}` |

You can combine an approval list with `enable` or `disable` in the same filter object. An approval list alone does not restrict which tools are available.

When execution needs approval, catch `ComposioToolInputRequiredError` from `@composio/core` in TypeScript or `ToolInputRequiredError` from `composio.exceptions` in Python. Display `inputRequests` (`input_requests`) and wait for the person's answers. Repeat the same tool or meta-tool call with `inputResponses` and `requestState` (`input_responses` and `request_state`), preserving the state from the error. Forward decline and cancel answers unchanged. See [handling input requests](https://composio-preview.mintlify.site/docs/how-composio-works.md#handling-requests-for-user-input) for the continuation flow.

For MCP clients, configure the [approval fallback](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md#approval-without-elicitation-support) if the client cannot ask for approval.

## Enabling toolkits

To limit a session to specific toolkits, pass an array of toolkit slugs. The agent can only discover and use tools from these toolkits.

> [tab] Python
>
> ```python theme={null}
> # Using array format
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["github", "gmail", "slack"]
> )
>
> # Using object format with enable key
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits={"enable": ["github", "gmail", "slack"]}
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // Using array format
> const session = await composio.create("user_123", {
>   toolkits: ["github", "gmail", "slack"],
> });
>
> // Using object format with enable key
> const session2 = await composio.create("user_123", {
>   toolkits: { enable: ["github", "gmail", "slack"] },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "toolkits": {"enable": ["github", "gmail", "slack"]}}'
> ```

## Disabling toolkits

To keep every toolkit discoverable except a few, use the `disable` syntax. This is useful when you want broad access but need to exclude specific toolkits.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits={"disable": ["exa", "firecrawl"]}
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   toolkits: { disable: ["exa", "firecrawl"] },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "toolkits": {"disable": ["exa", "firecrawl"]}}'
> ```

## Denying every app toolkit

An explicit empty allowlist means no app toolkits at all. Omitting `toolkits` keeps the unrestricted default, and an empty `disable` list is also unrestricted. The three requests are different:

| Toolkit config | Effect |
| - | - |
| Omitted | Every toolkit in the catalog is available |
| `{ enable: [] }` | No app toolkit is listed, searchable, executable, or served over MCP |
| `{ disable: [] }` | Every toolkit in the catalog is available |

Use an empty allowlist when a session should only run [custom tools](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md) or session helpers. Meta tools such as `COMPOSIO_SEARCH_TOOLS`, connection management, and the sandbox keep their own enablement, so `session.tools()` can still return them.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits={"enable": []},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   toolkits: { enable: [] },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "toolkits": {"enable": []}}'
> ```

> [!NOTE]
>
> Requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (Python) when you narrow an existing session with `session.update()`. Both SDKs send the empty allowlist as `{ enable: [] }`; the backend previously read an empty allowlist as "allow every toolkit", which left the session unrestricted.

The session API rejects unknown root keys with a `400` before it creates anything. A typo such as a singular `toolkit` fails the request instead of silently creating an unrestricted session.

## Direct tools preset

The direct tools preset preloads every tool allowed by session filters into the session's tool list and disables session meta tools by default. Use it for specialized agents with a narrow tool set that don't need dynamic tool discovery, in-chat auth, or workbench helpers.

This is not the default mode for broad agents. The default session behavior keeps meta tools available so the agent can search for relevant tools and avoid context bloat.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
> from composio_openai_agents import OpenAIAgentsProvider
>
> composio = Composio(
>     api_key="your_api_key",
>     provider=OpenAIAgentsProvider(),
> )
>
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["gmail"],
>     tools={
>         "gmail": {
>             "enable": [
>                 "GMAIL_FETCH_EMAILS",
>                 "GMAIL_CREATE_EMAIL_DRAFT",
>             ],
>         },
>     },
>     session_preset=SESSION_PRESET_DIRECT_TOOLS,
> )
>
> tools = session.tools()
> print([tool.name for tool in tools])
> # GMAIL_FETCH_EMAILS
> # GMAIL_CREATE_EMAIL_DRAFT
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, SessionPreset } from '@composio/core';
> import { OpenAIAgentsProvider } from '@composio/openai-agents';
>
> const composio = new Composio({
>   apiKey: 'your_api_key',
>   provider: new OpenAIAgentsProvider(),
> });
> const session = await composio.create("user_123", {
>   toolkits: ["gmail"],
>   tools: {
>     gmail: {
>       enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
>     },
>   },
>   sessionPreset: SessionPreset.DIRECT_TOOLS,
> });
>
> const tools = await session.tools();
> console.log(tools.map((tool) => tool.name));
> // GMAIL_FETCH_EMAILS
> // GMAIL_CREATE_EMAIL_DRAFT
> ```

> [tab] API
>
> ```bash theme={null}
> # The direct tools preset turns off meta tools, preloads every allowed tool, and disables search and multi-execute
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["gmail"]},
>     "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},
>     "manage_connections": {"enable": false},
>     "workbench": {"enable": false},
>     "preload": {"tools": "all"},
>     "search": {"enable": false},
>     "execute": {"enable_multi_execute": false}
>   }' | jq -r '.session_id')
>
> curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[].slug'
> ```

### Enable selected meta tools

With the direct tools preset, you can re-enable supported meta tool groups that your agent still needs. This session loads Gmail tools upfront while keeping connection management and workbench support available:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
> from composio_openai_agents import OpenAIAgentsProvider
>
> composio = Composio(
>     api_key="your_api_key",
>     provider=OpenAIAgentsProvider(),
> )
>
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["gmail"],
>     tools={
>         "gmail": {
>             "enable": [
>                 "GMAIL_FETCH_EMAILS",
>                 "GMAIL_CREATE_EMAIL_DRAFT",
>             ],
>         },
>     },
>     session_preset=SESSION_PRESET_DIRECT_TOOLS,
>     manage_connections={
>         "enable": True,
>     },
>     sandbox={
>         "enable": True,
>     },
> )
>
> tools = session.tools()
> print([tool.name for tool in tools])
> # GMAIL_FETCH_EMAILS
> # GMAIL_CREATE_EMAIL_DRAFT
> # COMPOSIO_MANAGE_CONNECTIONS
> # COMPOSIO_REMOTE_WORKBENCH
> # COMPOSIO_REMOTE_BASH_TOOL
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, SessionPreset } from '@composio/core';
> import { OpenAIAgentsProvider } from '@composio/openai-agents';
>
> const composio = new Composio({
>   apiKey: 'your_api_key',
>   provider: new OpenAIAgentsProvider(),
> });
> const session = await composio.create("user_123", {
>   toolkits: ["gmail"],
>   tools: {
>     gmail: {
>       enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
>     },
>   },
>   sessionPreset: SessionPreset.DIRECT_TOOLS,
>   manageConnections: {
>     enable: true,
>   },
>   sandbox: {
>     enable: true,
>   },
> });
>
> const tools = await session.tools();
> console.log(tools.map((tool) => tool.name));
> // GMAIL_FETCH_EMAILS
> // GMAIL_CREATE_EMAIL_DRAFT
> // COMPOSIO_MANAGE_CONNECTIONS
> // COMPOSIO_REMOTE_WORKBENCH
> // COMPOSIO_REMOTE_BASH_TOOL
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["gmail"]},
>     "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},
>     "manage_connections": {"enable": true},
>     "workbench": {"enable": true},
>     "preload": {"tools": "all"},
>     "search": {"enable": false},
>     "execute": {"enable_multi_execute": false}
>   }' | jq -r '.session_id')
>
> curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[].slug'
> ```

## Enabling or disabling specific tools

To control which individual tools are available within a toolkit, use the `tools` configuration. The key is the toolkit slug and the value specifies which tools to enable or disable.

To enable only specific tools, pass an `enable` list per toolkit:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tools={
>         # Only these Gmail tools will be available
>         "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
>         # Only issue-related GitHub tools
>         "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   tools: {
>     // Only these Gmail tools will be available
>     gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },
>     // Only issue-related GitHub tools
>     github: { enable: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"] }
>   }
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "tools": {
>       "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
>       "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
>     }
>   }'
> ```

The shorthand array syntax is equivalent to `enable`:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tools={
>         "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
>         "github": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   tools: {
>     gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
>     github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
>   }
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # The SDK expands the array shorthand to {"enable": [...]}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "tools": {
>       "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]},
>       "github": {"enable": ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]}
>     }
>   }'
> ```

To keep every tool in a toolkit except a few, use `disable`:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tools={
>         # All Slack tools except delete
>         "slack": {"disable": ["SLACK_DELETE_MESSAGE"]},
>         # All GitHub tools except destructive ones
>         "github": {"disable": ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"]}
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   tools: {
>     // All Slack tools except delete
>     slack: { disable: ["SLACK_DELETE_MESSAGE"] },
>     // All GitHub tools except destructive ones
>     github: { disable: ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"] }
>   }
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "tools": {
>       "slack": {"disable": ["SLACK_DELETE_MESSAGE"]},
>       "github": {"disable": ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"]}
>     }
>   }'
> ```

## Filtering tools by tags

Every tool has a [hint](https://composio-preview.mintlify.site/docs/governance/tool-hints.md) for the type of action it takes: `readOnlyHint`, `createHint`, `updateHint` or `destructiveHint`. Use the `tags` configuration to set what happens to each type of tool:

* **Allow:** leave the hint out. This is the default.
* **Block:** add the hint to `tags.disable`. The agent can't see or call these tools.
* **Require approval:** add the hint to `tags.require_approval`. These tools wait for the user's approval before they run. See [Approvals](https://composio-preview.mintlify.site/docs/governance/approvals.md).

For example, to block every tool that can delete something:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tags={"disable": ["destructiveHint"]}
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   tags: { disable: ["destructiveHint"] }
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "tags": {"disable": ["destructiveHint"]}}'
> ```

### Overriding for a toolkit

The session-wide `tags` apply to the tools of every toolkit. To handle a toolkit's tools differently, override them in `tools.<toolkit>.tags`. The override replaces the session-wide `tags` for that toolkit, so list everything you still want to block for it.

For example, this session blocks tools that update or delete everywhere, but overrides GitHub so only its tools that delete are blocked:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     # Everywhere: block tools that update or delete
>     tags={"disable": ["updateHint", "destructiveHint"]},
>     tools={
>         # GitHub: block only tools that delete
>         "github": {"tags": {"disable": ["destructiveHint"]}}
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   // Everywhere: block tools that update or delete
>   tags: { disable: ["updateHint", "destructiveHint"] },
>   tools: {
>     // GitHub: block only tools that delete
>     github: { tags: { disable: ["destructiveHint"] } }
>   }
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "tags": {"disable": ["updateHint", "destructiveHint"]},
>     "tools": {"github": {"tags": {"disable": ["destructiveHint"]}}}
>   }'
> ```

Listing a toolkit's tools with `enable` or `disable`, as in [Enabling or disabling specific tools](#enabling-or-disabling-specific-tools), also overrides the session-wide `tags` for that toolkit.

## Preloading tools

Return a known set of tools directly from `session.tools()` and the session MCP tool list, without the agent searching for them first.

By default, sessions expose [meta tools](https://composio-preview.mintlify.site/toolkits/meta-tools) that let the agent discover app tools at runtime. Use `preload.tools` when you already know which tools the agent needs, so it can call them without going through search each time.

Keep the preloaded set small, generally fewer than 20 tools, to avoid context bloat.

> [!NOTE]
>
> Requires `@composio/core` ≥ `0.9.0` (TypeScript) or `composio` ≥ `0.13.0` (Python). Older SDKs do not support `preload.tools`, `sessionPreset` / `session_preset`, or custom-tool `preload`.

> [!NOTE]
>
> `preload.tools` is not supported when `multiAccount.enable` is true. See [Managing multiple connected accounts](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md).

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio_openai_agents import OpenAIAgentsProvider
>
> composio = Composio(
>     api_key="your_api_key",
>     provider=OpenAIAgentsProvider(),
> )
>
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["gmail"],
>     preload={
>         "tools": [
>             "GMAIL_FETCH_EMAILS",
>             "GMAIL_CREATE_EMAIL_DRAFT",
>         ],
>     },
> )
>
> tools = session.tools()
> print([tool.name for tool in tools])
> # GMAIL_FETCH_EMAILS
> # GMAIL_CREATE_EMAIL_DRAFT
> # COMPOSIO_SEARCH_TOOLS
> # ... other default meta tools
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> import { OpenAIAgentsProvider } from '@composio/openai-agents';
>
> const composio = new Composio({
>   apiKey: 'your_api_key',
>   provider: new OpenAIAgentsProvider(),
> });
> const session = await composio.create("user_123", {
>   toolkits: ["gmail"],
>   preload: {
>     tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
>   },
> });
>
> const tools = await session.tools();
> console.log(tools.map((tool) => tool.name));
> // GMAIL_FETCH_EMAILS
> // GMAIL_CREATE_EMAIL_DRAFT
> // COMPOSIO_SEARCH_TOOLS
> // ... other default meta tools
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["gmail"]},
>     "preload": {"tools": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}
>   }' | jq -r '.session_id')
>
> curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[].slug'
> ```

For SDK custom tools, set `preload: true` on the custom tool or custom toolkit. See [Preloading custom tools](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md#preloading-custom-tools).

To preload every tool allowed by the session filters, use the `preload.tools = "all"` shortcut (`preload={"tools": "all"}` in Python, `preload: { tools: "all" }` in TypeScript). The `all` shorthand works for both Composio tools and SDK custom tools.

## Custom auth configs

Use your own OAuth credentials instead of Composio's defaults. Pass an auth config ID per toolkit:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     auth_configs={
>         "github": "ac_your_github_config",
>         "slack": "ac_your_slack_config"
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   authConfigs: {
>     github: "ac_your_github_config",
>     slack: "ac_your_slack_config",
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "auth_configs": {"github": "ac_your_github_config", "slack": "ac_your_slack_config"}
>   }'
> ```

See [White-labeling authentication](https://composio-preview.mintlify.site/docs/authentication/white-labeling-authentication.md) for branding, or [Managed vs custom auth](https://composio-preview.mintlify.site/docs/authentication/custom-app-vs-managed-app.md) for toolkits that require your own credentials.

## Account selection

When a user has multiple connected accounts for the same toolkit, specify which one the session uses:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     connected_accounts={
>         "gmail": ["ca_work_gmail"],
>         "github": ["ca_personal_github"],
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   connectedAccounts: {
>     gmail: ["ca_work_gmail"],
>     github: ["ca_personal_github"],
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "connected_accounts": {"gmail": ["ca_work_gmail"], "github": ["ca_personal_github"]}
>   }'
> ```

> [!NOTE]
>
> Arrays are the preferred format for `connectedAccounts`. A single string (e.g. `"ca_work_gmail"`) is still accepted for backwards compatibility and is automatically coerced to a single-element array. Only one account per toolkit is allowed when [multi-account mode](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md) is disabled.

### Precedence

When executing a tool, the session selects the connected account in this order:

1. The `connectedAccounts` override, if provided in the session config.
2. The `authConfigs` override, which finds or creates a connection on that config.
3. An auth config previously created for this toolkit.
4. A new auth config created using Composio managed auth.
5. Otherwise, an error if no Composio managed auth scheme exists for the toolkit.

When a user has multiple connected accounts for a toolkit, the session uses the most recently connected one.

## Disabling the sandbox

By default, sessions include the [sandbox](https://composio-preview.mintlify.site/docs/sandbox/remote.md), a persistent environment that provides `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL`. If your use case doesn't need code execution, disable it:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     sandbox={
>         "enable": False
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   sandbox: {
>     enable: false,
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # The REST API names the sandbox block `workbench`
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "workbench": {"enable": false}}'
> ```

When disabled:

* `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL` are excluded from the session
* Sandbox-related system prompt lines are stripped
* Direct sandbox calls are rejected with a 400 error

[Zero Data Retention](https://composio-preview.mintlify.site/docs/security/zero-data-retention.md) does not cover the sandbox, so disable it in sessions that handle data that needs ZDR.

To keep the sandbox but block raw HTTP calls from it, set `enable_proxy_execution` (Python) or `enableProxyExecution` (TypeScript) to `false`. See [Proxy execute](https://composio-preview.mintlify.site/docs/extending-sessions/proxy-execute.md#session-restrictions) for how session restrictions apply to proxy calls.

> [!NOTE]
>
> `sandbox` is the preferred config key. `workbench` still works as a fully supported alias and isn't deprecated, so existing code keeps running unchanged.

## Sandbox compute tier

The sandbox runs per session. Pick a compute tier to match the workload: heavier code execution or larger in-memory data benefits from a bigger sandbox. Pass the tier via `sandbox.sandbox_size` (snake\_case on the wire, `sandboxSize` in the TypeScript SDK).

> [!NOTE]
>
> Requires `@composio/core` ≥ `0.8.1` (TypeScript) or `composio` ≥ `0.12.1` (Python). Older SDKs reject `sandboxSize` (TypeScript) or silently drop `sandbox_size` (Python). See the [release notes](https://composio-preview.mintlify.site/docs/changelog/2026/04/28).

| Tier | vCPU | RAM |
| - | - | - |
| `standard` | 1 | 1 GB |
| `medium` | 2 | 2 GB |
| `large` | 4 | 4 GB |
| `xlarge` | 8 | 8 GB |

Defaults to `standard` when omitted.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     sandbox={
>         "enable": True,
>         "sandbox_size": "large",
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   sandbox: {
>     enable: true,
>     sandboxSize: "large",
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "workbench": {"enable": true, "sandbox_size": "large"}}'
> ```

> [!NOTE]
>
> **Pricing:** Sandboxes are not billed today. Composio plans to begin billing for sandbox usage soon (metered by tier and runtime). Pick a tier that matches your workload, but expect future pricing to track actual usage.

Changing `sandbox_size` on an existing session recreates the sandbox on the next access. The sandbox's in-memory filesystem state is lost, but the persistent [`/mnt/files/` mount](https://composio-preview.mintlify.site/docs/sandbox/remote#files-and-mounts) survives the restart.

## Updating a session

`session.update()` patches the stored configuration in place. Fields you omit are preserved, so you can widen or narrow one part of a session without restating the rest. The SDK refreshes `session.config` and the session's config version only after the API accepts the change.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.use("session_id")
>
> session.update(toolkits={"enable": ["gmail", "github"]})
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
>
> await session.update({ toolkits: { enable: ["gmail", "github"] } });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkits": {"enable": ["gmail", "github"]}}'
> ```

> [!NOTE]
>
> The update behavior below requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (Python).

### Maps replace, they don't merge

A `tools`, `authConfigs`, or `connectedAccounts` map you send replaces the stored map entirely. The API does not merge entries, so a Slack-only `tools` map removes a Gmail entry that was stored before it.

Stored before the update:

```json theme={null}
{
  "tools": {
    "gmail": { "enable": ["GMAIL_FETCH_EMAILS"] },
    "slack": { "enable": ["SLACK_SEND_MESSAGE"] }
  }
}
```

The update:

> [tab] Python
>
> ```python theme={null}
> session.update(
>     tools={"slack": {"enable": ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"]}},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
> await session.update({
>   tools: { slack: { enable: ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"] } },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"tools": {"slack": {"enable": ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"]}}}'
> ```

Stored after the update. The `gmail` entry is gone:

```json theme={null}
{
  "tools": {
    "slack": { "enable": ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"] }
  }
}
```

To change one entry, send the whole map with every entry you want to keep. An empty map (`{}`) is stored as an explicit empty map.

The same rule applies to `toolkits`, `tags`, and `preload`: a value replaces the stored policy. `manageConnections`, `sandbox`, and `multiAccount` merge the subfields you send, and an empty object changes nothing.

### Narrowing an existing session to no app toolkits

An empty allowlist on update denies every app toolkit, exactly as it does on create. The SDK sends `{ "enable": [] }` as-is instead of dropping it from the request.

> [tab] Python
>
> ```python theme={null}
> session.update(toolkits={"enable": []})
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
> await session.update({ toolkits: { enable: [] } });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkits": {"enable": []}}'
> ```

### Removing a callback URL

`manageConnections.callbackUrl: null` removes only the stored callback URL. `enable` and the other connection settings stay as they are. An empty string is rejected.

> [tab] Python
>
> ```python theme={null}
> session.update(manage_connections={"callback_url": None})
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
> await session.update({ manageConnections: { callbackUrl: null } });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"manage_connections": {"callback_url": null}}'
> ```

### Clearing a block with null

Passing `null` (`None` in Python) for a whole block removes the stored override and the session falls back to the default for that block. Every policy block accepts it: `toolkits`, `tools`, `tags`, `authConfigs`, `connectedAccounts`, `preload`, `manageConnections`, `sandbox`, `proxyExecute`, `multiAccount`, `search`, `execute`, and `experimental`.

> [tab] Python
>
> ```python theme={null}
> session.update(manage_connections=None, multi_account=None)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
> await session.update({ manageConnections: null, multiAccount: null });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"manage_connections": null, "multi_account": null}'
> ```

Clearing a policy can widen access. `toolkits: null` removes the toolkit policy and restores the unrestricted default, which is the opposite of `{ "enable": [] }`; clearing `preload` does the same for preloaded tools, so the agent can reach more than before the update. Send `toolkits: []` when you want to deny every app toolkit. Clearing `multiAccount` resolves to disabled, while omitting it preserves the stored setting.

### Blocks you can set only on update

`search`, `execute`, and `experimental` are not part of `create()`. Reach them with `session.update()` on an existing session.

> [tab] Python
>
> ```python theme={null}
> session.update(
>     search={"enable": False},
>     execute={"enable_multi_execute": False},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
> await session.update({
>   search: { enable: false },
>   execute: { enableMultiExecute: false },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"search": {"enable": false}, "execute": {"enable_multi_execute": false}}'
> ```

Both blocks are on by default. `search` controls the session's search helper, so disabling it leaves the agent with the tools you preloaded. `execute.enableMultiExecute` controls whether the agent can run several tool calls in one request. `manageConnections.enableConnectionRemoval` is update-only as well, and controls whether the session exposes the connection-removal tool.

The `experimental` block on update holds server-side session settings: `permissions`, `linkUrlOverwrite`, `fastMode`, `submitFeedback`, and `sessionConfigId`. `sessionConfigId` applies a [saved Session config](https://composio-preview.mintlify.site/docs/session-configs.md#applying-a-config-to-an-existing-session) and can't be combined with `toolkits`, `tools`, or `tags`. The `experimental` block on update is a different field from the `experimental` option on `create()`, which holds [custom tools and toolkits](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md) that run in your process, so `experimental: null` on an update leaves those alone.

### Multi-account mode after an update

The canonical disabled state is `{ "enable": false, "require_explicit_selection": false }` with no maximum. Sending `enable: false` resets a stale maximum or selection setting, and reapplying that disabled configuration is accepted. Combining `enable: false` with `maxAccountsPerToolkit` or `requireExplicitSelection: true` is rejected with a `400`.

### Preload must stay inside the policy

An update that narrows `toolkits`, `tools`, or `tags` while leaving an explicitly preloaded tool outside the new policy is rejected with a `400`, and nothing changes. Fix `preload` in the same update:

> [tab] Python
>
> ```python theme={null}
> session.update(
>     toolkits={"enable": ["slack"]},
>     preload={"tools": ["SLACK_SEND_MESSAGE"]},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.sessions.use("session_id");
> await session.update({
>   toolkits: { enable: ["slack"] },
>   preload: { tools: ["SLACK_SEND_MESSAGE"] },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkits": {"enable": ["slack"]}, "preload": {"tools": ["SLACK_SEND_MESSAGE"]}}'
> ```

### Concurrent updates

Every session response carries a config version (`session.configVersion` in TypeScript, `session.config_version` in Python, `config_version` on the wire). By default, `session.update()` sends no precondition, so the last writer wins. To make an update conditional, pass the version you read as `expectedConfigVersion` (`expected_config_version` in Python). The API then applies the update only when the stored version still matches. Otherwise it answers `409` and writes nothing: no config change, no history entry, no cache update. The SDK never retries that request, so a conflict is reported exactly once.

> [!NOTE]
>
> The API must support `expected_config_version`. If it doesn't, it rejects a conditional update with a `400`.

On a conflict, the SDK raises `ComposioSessionConfigConflictError` (TypeScript) or `SessionConfigConflictError` (Python) and leaves the session object as it was. Re-read the session with `sessions.use()`, reapply your change on top of the fresh config, and retry:

> [tab] Python
>
> ```python theme={null}
> from composio.exceptions import SessionConfigConflictError
>
> session = composio.sessions.use("session_id")
>
> try:
>     session.update(
>         toolkits={"enable": ["gmail", "github"]},
>         expected_config_version=session.config_version,
>     )
> except SessionConfigConflictError:
>     # Another client changed the session first. Nothing was written.
>     session = composio.sessions.use("session_id")
>     session.update(
>         toolkits={"enable": ["gmail", "github"]},
>         expected_config_version=session.config_version,
>     )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, ComposioSessionConfigConflictError } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> let session = await composio.sessions.use("session_id");
>
> try {
>   await session.update({
>     toolkits: { enable: ["gmail", "github"] },
>     expectedConfigVersion: session.configVersion,
>   });
> } catch (error) {
>   if (!(error instanceof ComposioSessionConfigConflictError)) throw error;
>   // Another client changed the session first. Nothing was written.
>   session = await composio.sessions.use("session_id");
>   await session.update({
>     toolkits: { enable: ["gmail", "github"] },
>     expectedConfigVersion: session.configVersion,
>   });
> }
> ```

> [tab] API
>
> ```bash theme={null}
> CONFIG_VERSION=$(curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.config_version')
>
> # Returns 409 and writes nothing if another client changed the session first.
> # Re-read config_version and retry.
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkits": {"enable": ["gmail", "github"]}, "expected_config_version": '"$CONFIG_VERSION"'}'
> ```

You can also pass a version you read elsewhere, for example one stored with a queued job. `expectedConfigVersion: false` (`expected_config_version=False`) is the same as omitting it. The API still commits only a fully validated configuration, so a losing update never leaves a half-applied session behind.

Raw HTTP callers set `expected_config_version` in the `PATCH` body themselves; without it the last writer wins.

To roll a session back, read a previous configuration from its config history (`GET /api/v3.1/tool_router/session/{session_id}/config_history`) and convert it into an update request. A history entry is not a request body: it carries metadata and version fields, and it names toolkits and tools as `enabled` and `disabled`, which map to `enable` and `disable` in the update.

## Session methods

For framework examples, see provider-specific documentation like [OpenAI](https://composio-preview.mintlify.site/docs/providers/openai.md) or [Vercel AI SDK](https://composio-preview.mintlify.site/docs/providers/vercel.md). To connect over MCP instead, see [Using sessions via MCP](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md).

### tools()

Get the tools the session exposes for your AI framework. By default these are the session's [meta tools](https://composio-preview.mintlify.site/toolkits/meta-tools), formatted for your configured provider.

> [tab] Python
>
> ```python theme={null}
> tools = session.tools()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const tools = await session.tools();
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

### executeMeta() / execute\_meta()

Run a `COMPOSIO_*` [meta tool](https://composio-preview.mintlify.site/toolkits/meta-tools) directly from your session with a slug and optional arguments:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
> session = composio.create(user_id="user_123")
> result = session.execute_meta(
>     "COMPOSIO_SEARCH_TOOLS",
>     arguments={"queries": [{"use_case": "send an email"}]},
> )
> print(result.data, result.result_type)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const result = await session.executeMeta("COMPOSIO_SEARCH_TOOLS", {
>   queries: [{ use_case: "send an email" }],
> });
> console.log(result.data, result.resultType);
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123"}' | jq -r '.session_id')
>
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute_meta \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"slug": "COMPOSIO_SEARCH_TOOLS", "arguments": {"queries": [{"use_case": "send an email"}]}}'
> ```

The exported `ToolRouterSessionMetaToolSlug` type lists the accepted slugs. The response includes `resultType` (`result_type` in Python). If execution needs input, such as approval, the SDK raises `ComposioToolInputRequiredError` (`ToolInputRequiredError` in Python). Calls are sent once without retries, so retry only when the operation is safe to repeat.

In TypeScript, the third argument holds input-response options: `session.executeMeta(slug, args, { inputResponses, requestState })`. Request options belong in the fourth argument. To pass only request options, use `session.executeMeta(slug, args, undefined, requestOptions)`.

`COMPOSIO_MULTI_EXECUTE_TOOL` calls through this method run on the backend. Custom tools named in those calls are not executed in your process.

### authorize()

Manually authenticate a user to a toolkit outside of the chat flow.

> [tab] Python
>
> ```python theme={null}
> connection_request = session.authorize(
>     "github",
>     callback_url="https://myapp.com/callback",
> )
>
> print(connection_request.redirect_url)
>
> connected_account = connection_request.wait_for_connection()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const connectionRequest = await session.authorize("github", {
>   callbackUrl: "https://myapp.com/callback",
> });
>
> console.log(connectionRequest.redirectUrl);
>
> const connectedAccount = await connectionRequest.waitForConnection();
> ```

> [tab] API
>
> ```bash theme={null}
> curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit": "github", "callback_url": "https://myapp.com/callback"}' | jq -r '.redirect_url'
> ```

For more details, see [Manually authenticating users](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md).

### toolkits()

List the toolkits enabled for the session and their connection status, sorted by popularity. Use it to build a UI showing which apps are connected. Each toolkit includes its `slug`, `name`, `logo`, and connection status, and the call returns the first 20 by default.

> [tab] Python
>
> ```python theme={null}
> toolkits = session.toolkits()
>
> for toolkit in toolkits.items:
>     connection = toolkit.connection
>     if connection and connection.is_active and connection.connected_account:
>         status = connection.connected_account.id
>     else:
>         status = "Not connected"
>     print(f"{toolkit.name}: {status}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const toolkits = await session.toolkits();
>
> toolkits.items.forEach((toolkit) => {
>   console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

Filter to only connected toolkits:

> [tab] Python
>
> ```python theme={null}
> connected = session.toolkits(is_connected=True)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const connected = await session.toolkits({ isConnected: true });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

Paginate through every toolkit with `limit` and the returned cursor:

> [tab] Python
>
> ```python theme={null}
> all_toolkits = []
> cursor = None
>
> while True:
>     result = session.toolkits(limit=20, next_cursor=cursor)
>     all_toolkits.extend(result.items)
>     cursor = result.next_cursor
>     if not cursor:
>         break
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const allToolkits: any[] = [];
> let cursor: string | undefined;
>
> do {
>   const { items, cursor: nextCursor } = await session.toolkits({ limit: 20, cursor });
>   allToolkits.push(...items);
>   cursor = nextCursor;
> } while (cursor);
> ```

> [tab] API
>
> ```bash theme={null}
> CURSOR=""
> while true; do
>   PAGE=$(curl -s -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?limit=20${CURSOR:+&cursor=$CURSOR}" \
>     -H "x-api-key: $COMPOSIO_API_KEY")
>   echo "$PAGE" | jq -c '.items[]'
>   CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty')
>   [ -z "$CURSOR" ] && break
> done
> ```

### update()

Patch the session configuration in place. See [Updating a session](#updating-a-session) for what omitted fields, replaced maps, `null`, and `expectedConfigVersion` do.

> [tab] Python
>
> ```python theme={null}
> config = session.update(toolkits={"enable": ["gmail", "github"]})
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const config = await session.update({ toolkits: { enable: ["gmail", "github"] } });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkits": {"enable": ["gmail", "github"]}}'
> ```

### Configuration history

Inspect the configurations a session has used with `session.list_config_history(limit=10)` in Python or `await session.listConfigHistory({ limit: 10 })` in TypeScript. Results are newest first, with the live configuration first. Each `session.update()` archives the previous configuration.

The response contains `items` with each version's `config` and an `is_current` (Python) or `isCurrent` (TypeScript) flag. Pass the response's `next_cursor` (Python) or `nextCursor` (TypeScript) as `cursor` to fetch another page; `limit` supports up to 100 items per page.

### delete()

Delete a session when you're done with it. Deleted sessions immediately stop being retrievable or executable, and the call returns the deleted `session_id`. Deleting a missing or already-deleted session surfaces the backend `404`.

> [!NOTE]
>
> Requires `@composio/core` ≥ `0.13.1` (TypeScript) or `composio` ≥ `0.17.1` (Python).

> [tab] Python
>
> ```python theme={null}
> result = session.delete()
> print(result["session_id"], result["deleted"])
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create('user_123');
> const result = await session.delete();
> console.log(result.sessionId, result.deleted);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X DELETE https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

## Browsing the catalog

Before configuring a session, explore the toolkits and tools available. Browse them visually at [dashboard.composio.dev](https://dashboard.composio.dev?utm_source=docs\&utm_medium=content\&utm_campaign=docs-configuring-sessions) or in the [docs catalog](https://composio-preview.mintlify.site/toolkits.md), or fetch them programmatically:

> [tab] Python
>
> ```python theme={null}
> # List toolkits
> toolkits = composio.toolkits.get()
>
> # List tools within a toolkit (top 20 by default)
> tools = composio.tools.get("user_123", toolkits=["GITHUB"])
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> // List toolkits
> const toolkits = await composio.toolkits.get();
>
> // List tools within a toolkit (top 20 by default)
> const tools = await composio.tools.get(userId, { toolkits: ["GITHUB"] });
> ```

> [tab] API
>
> ```bash theme={null}
> # List toolkits
> curl -X GET https://backend.composio.dev/api/v3.1/toolkits \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # List tools within a toolkit (top 20 by default)
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=GITHUB&limit=20" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

Inspect a tool's input and output schema without a user context with `getRawComposioToolBySlug`:

> [tab] Python
>
> ```python theme={null}
> tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL")
> print(tool.name)
> print(tool.description)
> print(tool.input_parameters)
> print(tool.output_parameters)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL");
> console.log(tool.name);
> console.log(tool.description);
> console.log(tool.inputParameters);
> console.log(tool.outputParameters);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/tools/GMAIL_SEND_EMAIL \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

To fetch several toolkits in one request, use `composio.toolkits.get_many(["github", "slack"])` in Python or `await composio.toolkits.getMany(['github', 'slack'])` in TypeScript. Both return the matching toolkits.

## Next

> [card] [Sandbox](https://composio-preview.mintlify.site/docs/sandbox/remote.md)
>
> Give sessions a persistent compute environment with COMPOSIO\_REMOTE\_WORKBENCH and COMPOSIO\_REMOTE\_BASH\_TOOL
