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

# Sessions

> First-class API for creating and reusing Composio sessions.  `composio.sessions.create(...)` is the canonical session creation entrypoint. The top-level `composio.create(...)` method remains as a backwards-compatible alias for `composio.sessions.create(...)`.

## Usage

Access this class through the `composio.sessions` property:

```typescript theme={null}
const composio = new Composio({ apiKey: 'your-api-key' });
const result = await composio.sessions.list();
```

## Methods

### create()

Creates a new tool router session for a user. Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools should be exposed directly; see `ToolRouterCreateSessionConfig`.

The session's MCP config carries the session credential only when the MCP URL shares the origin of the configured API base URL. When it does not, `mcp: true` makes the call throw `ComposioMCPDestinationError` (naming both origins, never a key); without `mcp: true` the session is returned with `session.mcp.headers` empty and a warning naming both origins is logged, so native tools keep working.

**Overload 1**

```typescript theme={null}
async create(userId: string, config: ToolRouterCreateSessionConfig & { mcp: true }, requestOptions?: ComposioRequestOptions): Promise<Session<TToolCollection, TTool, TProvider>>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `userId` | `string` | \{string} The user id to create the session for |
| `config` | `ToolRouterCreateSessionConfig & \{ mcp: true \}` | \{ToolRouterCreateSessionConfig} The config for the tool router session |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<Session<TToolCollection, TTool, TProvider>>` — The tool router session

**Overload 2**

```typescript theme={null}
async create(userId: string, config?: ToolRouterCreateSessionConfig, requestOptions?: ComposioRequestOptions): Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `userId` | `string` | \{string} The user id to create the session for |
| `config?` | `ToolRouterCreateSessionConfig` | \{ToolRouterCreateSessionConfig} The config for the tool router session |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>` — The tool router session

**Example**

```typescript theme={null}
import { Composio } from '@composio/core';

const composio = new Composio();

const session = await composio.sessions.create('user_123', {
  toolkits: ['gmail'],
  manageConnections: true,
  experimental: {
    customTools: [myCustomTool],
    customToolkits: [myToolkit],
  },
});

// Start from a saved Session config instead of inline access fields
const configured = await composio.sessions.create('user_123', {
  authConfigs: { github: 'ac_123' },
  experimental: { sessionConfigId: 'sc_123' },
});
```

***

### delete()

Delete a tool router session by ID.

Deleted sessions immediately stop being retrievable or executable. Deleting a missing or already-deleted session surfaces the backend 404.

```typescript theme={null}
async delete(id: string, requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionDeleteResponse>
```

**Parameters**

| Name | Type |
| - | - |
| `id` | `string` |
| `requestOptions?` | `ComposioRequestOptions` |

**Returns**

`Promise<ToolRouterSessionDeleteResponse>`

***

### use()

Use an existing session

The session's MCP config carries the session credential only when the MCP URL shares the origin of the configured API base URL. When it does not, `mcp: true` makes the call throw `ComposioMCPDestinationError` (naming both origins, never a key); without `mcp: true` the session is returned with `session.mcp.headers` empty and a warning naming both origins is logged, so native tools keep working.

**Overload 1**

```typescript theme={null}
async use(id: string, options: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp: true }, requestOptions?: ComposioRequestOptions): Promise<Session<TToolCollection, TTool, TProvider>>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `id` | `string` | \{string} The id of the session to use |
| `options` | `\{ customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp: true \}` | |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<Session<TToolCollection, TTool, TProvider>>` — The tool router session

**Overload 2**

```typescript theme={null}
async use(id: string, options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean }, requestOptions?: ComposioRequestOptions): Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>
```

**Parameters**

| Name | Type | Description |
| - | - | - |
| `id` | `string` | \{string} The id of the session to use |
| `options?` | `\{ customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean \}` | |
| `requestOptions?` | `ComposioRequestOptions` | |

**Returns**

`Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>` — The tool router session

**Example**

```typescript theme={null}
import { Composio } from '@composio/core';

const composio = new Composio();
const id = 'session_123';
const session = await composio.sessions.use(id);

console.log(session.mcp.url);
console.log(session.mcp.headers);
```

***
