Sessions

Usage

Access this class through the composio.sessions property:

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

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

Parameters

Returns

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

Overload 2

async create(userId: string, config?: ToolRouterCreateSessionConfig, requestOptions?: ComposioRequestOptions): Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>

Parameters

Returns

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

Example

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.

async delete(id: string, requestOptions?: ComposioRequestOptions): Promise<{ deleted: true; sessionId: string }>

Parameters

Returns

Promise<\{ deleted: true; sessionId: string \}>

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

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

Parameters

Returns

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

Overload 2

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

Parameters

Returns

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

Example

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);