Session

Properties

Methods

authorize()

Initiate an authorization flow for a toolkit. Returns a ConnectionRequest with a redirect URL for the user.

Pass experimental: { accountType: 'SHARED', aclConfigForShared } to create a SHARED connection with a per-user ACL in one flow. Default behaviour (omit the block) creates a PRIVATE connection.

Experimental — shape may change in future releases.

aclConfigForShared is validated against the same caps as composio.connectedAccounts.link() (≤1000 entries per list, each userId 1..256 characters). Invalid input throws ValidationError at the SDK boundary.

async authorize(toolkit: string, options?: { alias?: string; callbackUrl?: string; experimental?: { accountType?: ConnectedAccountType; aclConfigForShared?: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] } } }, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>

Parameters

Returns

Promise<ConnectionRequest>

customToolkits()

List all custom toolkits registered in this session. Returns toolkits with their tools showing final slugs.

customToolkits(): RegisteredCustomToolkit[]

Returns

RegisteredCustomToolkit[] — Array of registered custom toolkits

customTools()

List all custom tools registered in this session. Returns tools with their final slugs, schemas, and resolved toolkit.

customTools(options?: { toolkit?: string }): RegisteredCustomTool[]

Parameters

Returns

RegisteredCustomTool[] — Array of registered custom tools

delete()

Delete this session.

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

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

Parameters

Returns

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

ensureConnected()

Ensure a toolkit has an active connection in this session, reconciling authorize()/session.link with the session's active connection state.

If the session already resolves an ACTIVE connection (or the toolkit is no-auth), this returns immediately without creating a link — unlike authorize(), which always starts a new link flow, even when one is already connected. Otherwise it starts the authorization flow and waits for the new connection to become ACTIVE.

For interactive flows that should surface the redirect URL instead of blocking, use authorize() and its waitForConnection() directly.

async ensureConnected(toolkit: string, options?: { alias?: string; callbackUrl?: string; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] } }; timeout?: number }, requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionEnsureConnectedResult>

Parameters

Returns

Promise<ToolRouterSessionEnsureConnectedResult> — The toolkit's canonical slug, whether it was already connected, and the active connected account (omitted for no-auth toolkits)

Example

const session = await composio.sessions.create({ toolkits: ['github'] });
const { wasConnected, connectedAccount } = await session.ensureConnected('github');
if (!wasConnected) console.log('Newly linked:', connectedAccount?.id);

execute()

Execute a tool within the session.

For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the original slug (e.g. "GREP") when that original slug is unique across the session's custom tools and toolkits. Custom tools are executed in-process; remote tools are sent to the Composio backend.

async execute(toolSlug: string, arguments_?: Record<string, unknown>, options?: ToolRouterSessionExecuteOptions, requestOptions?: ComposioRequestOptions): Promise<...>

Parameters

Returns

Promise<...> — The tool execution result

listConfigHistory()

Page through this session's configuration history, newest first. The first page starts with the live config (isCurrent: true); every session.update() archives the previous version as a history row.

async listConfigHistory(options?: { cursor?: string; limit?: number }, requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionListConfigHistoryResponse>

Parameters

Returns

Promise<ToolRouterSessionListConfigHistoryResponse> — The config versions on this page plus pagination info

Example

const { items, nextCursor } = await session.listConfigHistory({ limit: 10 });
console.log(items[0].version, items[0].isCurrent); // e.g. 3, true
console.log(items[1].config.toolkits);

proxyExecute()

Proxy an API call through Composio's auth layer using the session's connected account. The backend resolves the connected account from the toolkit within the session.

async proxyExecute(params: { body?: unknown; endpoint: string; method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; parameters?: { in: 'query' | 'header'; name: string; value: string | number }[]; toolkit: string }, requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionProxyExecuteResponse>

Parameters

Returns

Promise<ToolRouterSessionProxyExecuteResponse> — The proxied API response with status, data, headers

search()

Search for tools by semantic use case. Returns relevant tools for the given query with schemas and guidance.

async search(params: { query: string; toolkits?: string[] }, requestOptions?: ComposioRequestOptions): Promise<{ error: string | null; nextStepsGuidance: string[]; results: { difficulty?: string; error?: string | null; executionGuidance?: string; index: number; knownPitfalls?: string[]; memory?: Record<string, ...[]>; planId?: string; primaryToolSlugs: string[]; recommendedPlanSteps?: string[]; referenceWorkbenchSnippets?: { code: ...; description: ... }[]; relatedToolSlugs: string[]; toolkits: string[]; useCase: string }[]; session: { generateId: boolean; id: string; instructions: string }; success: boolean; timeInfo: { currentTimeUtc: string; currentTimeUtcEpochSeconds: number; message: string }; toolkitConnectionStatuses: { connectionDetails?: Record<string, unknown>; currentUserInfo?: Record<string, unknown>; description: string; hasActiveConnection: boolean; instantAccount?: { allowedToolSlugs: ...[] }; statusMessage: string; toolkit: string }[]; toolSchemas: Record<string, { description?: string; hasFullSchema?: boolean; inputSchema?: Record<string, unknown>; outputSchema?: Record<string, unknown>; schemaRef?: { args: { toolSlugs: ... }; message?: string; tool: 'COMPOSIO_GET_TOOL_SCHEMAS' }; toolkit: string; toolSlug: string }> }>

Parameters

Returns

Promise<\{ error: string \| null; nextStepsGuidance: string[]; results: \{ difficulty?: string; error?: string \| null; executionGuidance?: string; index: number; knownPitfalls?: string[]; memory?: Record<string, ...[]>; planId?: string; primaryToolSlugs: string[]; recommendedPlanSteps?: string[]; referenceWorkbenchSnippets?: \{ code: ...; description: ... \}[]; relatedToolSlugs: string[]; toolkits: string[]; useCase: string \}[]; session: \{ generateId: boolean; id: string; instructions: string \}; success: boolean; timeInfo: \{ currentTimeUtc: string; currentTimeUtcEpochSeconds: number; message: string \}; toolkitConnectionStatuses: \{ connectionDetails?: Record<string, unknown>; currentUserInfo?: Record<string, unknown>; description: string; hasActiveConnection: boolean; instantAccount?: \{ allowedToolSlugs: ...[] \}; statusMessage: string; toolkit: string \}[]; toolSchemas: Record<string, \{ description?: string; hasFullSchema?: boolean; inputSchema?: Record<string, unknown>; outputSchema?: Record<string, unknown>; schemaRef?: \{ args: \{ toolSlugs: ... \}; message?: string; tool: 'COMPOSIO_GET_TOOL_SCHEMAS' \}; toolkit: string; toolSlug: string \}> \}>

toolkits()

Query the connection state of toolkits in the session. Supports pagination and filtering by toolkit slugs.

async toolkits(options?: { cursor?: string; isConnected?: boolean; limit?: number; search?: string; toolkits?: string[] }, requestOptions?: ComposioRequestOptions): Promise<{ cursor: string | undefined; items: { connection?: { authConfig?: ... | ...; connectedAccount?: { id: ...; status: ... }; isActive: boolean }; isNoAuth: boolean; logo?: string; name: string; slug: string }[]; totalPages: number }>

Parameters

Returns

Promise<\{ cursor: string \| undefined; items: \{ connection?: \{ authConfig?: ... \| ...; connectedAccount?: \{ id: ...; status: ... \}; isActive: boolean \}; isNoAuth: boolean; logo?: string; name: string; slug: string \}[]; totalPages: number \}>

tools()

Get the tools available in the session, formatted for your AI framework. Requires a provider to be configured in the Composio constructor.

When custom tools are bound to the session, execution of COMPOSIO_MULTI_EXECUTE_TOOL is intercepted: local tools are executed in-process, remote tools are sent to the backend.

async tools(modifiers?: SessionMetaToolOptions, requestOptions?: ComposioRequestOptions): Promise<ReturnType>

Parameters

Returns

Promise<ReturnType>

update()

Partially update the session configuration.

Only the fields provided are changed; omitted fields are preserved. For each policy block null removes the stored override (which can increase access: toolkits: null restores the unrestricted default, while toolkits: [] denies every app toolkit and is sent as-is). Supplied tools, authConfigs and connectedAccounts maps replace the stored map entirely. manageConnections.callbackUrl: null removes only the stored callback URL.

By default the request carries no precondition: the last writer wins. Pass expectedConfigVersion (for example session.configVersion) to make the update conditional: the API then applies it only when the stored version still matches, and a concurrent change surfaces as ComposioSessionConfigConflictError (HTTP 409) instead of being overwritten. The API must support the expected_config_version field; otherwise it rejects the request with a 400. expectedConfigVersion: false is the same as omitting it. The PATCH is never retried by the transport, so a 409 is reported exactly once. On conflict this object is left unchanged: re-fetch the session with sessions.use(sessionId) and retry against the fresh configVersion.

experimental.sessionConfigId applies a saved Session config: it replaces the session's toolkit, tool and tag access and cannot be combined with toolkits, tools or tags (a ValidationError is thrown before any request). A 409 while applying it means the session or the config changed; re-fetch the session and retry. Backend 400, 403 and 404 errors, for example for an archived or missing config, surface unchanged.

config, configVersion, preload, sandbox, warnings and experimental.sourceSessionConfig are refreshed in place only after a successful response, and the updated config is returned.

async update(config: ToolRouterUpdateSessionConfig, requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionConfig>

Parameters

Returns

Promise<ToolRouterSessionConfig>