Skip to main content
These are Composio’s session endpoints. A session is the runtime context your agent uses to work for one of your users: it scopes which user’s connected accounts are in play, which tools are available, how authentication happens, and where execution state lives. Read What is a session? for the full concept.
Sessions were formerly called the “tool router”, which is why these endpoints live under tool_router. They are the same thing.
In the SDK you do not call these endpoints directly. Use composio.create(...) to start a session and composio.use(...) to resume one, then call session.tools(), session.execute(...), and session.authorize(...) on the returned object. Reach for the raw API when you need lower-level control: creating and patching a session config, attaching to an existing session, searching for tools, executing tools and meta tools, opening link sessions for auth, proxying authenticated requests, and reading or writing files in a session mount. See Configuring sessions for toolkits, auth configs, account selection, and presets.

List Session configs

List Session configs in your project, newest updated first. Returns active configs by default; set archived=true to list archived configs. Retrieve a config by ID for its description and toolkit, tool, and tag policy. Experimental: available only to projects enabled for Session configs. Create and manage configs in Dashboard.

Retrieve a Session config

Retrieve a saved access policy in your project. config.toolkits.enable selects toolkit slugs; config.toolkits.disable excludes them; an omitted config.toolkits allows all toolkits. Tool and tag rules further restrict access. This returns the saved policy, not an expanded catalog or an existing Session snapshot. Archived configs remain readable but cannot create new Sessions. Experimental: available only to projects enabled for Session configs. Create and manage configs in Dashboard.

Get a tool router session by ID (v3.1)

Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.

List a tool router session config history

Returns the session config history ordered by version DESC (newest first). The live (current) config appears once, on the first page only, with `is_current: true`; archived versions have `is_current: false`.

List files in a session mount

Lists files in a workbench session storage mount with cursor-based pagination. Use the download_url endpoint with the returned mount_relative_path to get a presigned download URL.

Get toolkits for a tool router session

Retrieves a cursor-paginated list of toolkits available in the tool router session. Includes toolkit metadata, composio-managed auth schemes, and connected accounts if available. Optionally filter by specific toolkit slugs.

List tools with schemas for a tool router session (v3.1)

Returns tools available in a tool router session with complete schemas. Results are paginated; use `next_cursor` to fetch the next page. Tools are returned in alphabetical order.

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.

Attach to an existing tool router session (v3.1)

Fetch an existing tool router session by ID.

Execute a tool within a tool router session

Execute a tool (meta or app) within an existing tool router session.

Execute a meta tool within a tool router session

Execute a Composio meta tool (COMPOSIO_*) within an existing tool router session.

Create a link session for a toolkit in a tool router session

Initiates an authentication link session for a specific toolkit within a tool router session. Returns a link token and redirect URL that users can use to complete the OAuth flow.

Delete a file from a session mount

Deletes a file from a workbench session storage mount. Deleting a non-existent file succeeds silently (idempotent).

Create a presigned download URL for a mount file

Generates a presigned download URL for a file in a workbench session mount. Accepts a relative path within the mount.

Create a presigned upload URL for a mount file

Generates a presigned upload URL for uploading a file to a workbench session mount. The caller should PUT the file content directly to the returned URL.

Execute proxy request within a tool router session

Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.

Search for tools using a query

Search for tools matching a use case query within an existing tool router session.

Patch a tool router session config (v3.1)

Partially updates an existing tool router session. Inline fields update only the supplied settings. Alternatively, experimental.session_config_id applies the latest active saved config from this project, replacing toolkit, tool, and tag access while preserving other settings. Later saved-config edits do not sync automatically. Uses optimistic concurrency control and retains the previous policy in config history.

Delete a tool router session

Deletes a tool router session. The session immediately stops being retrievable and executable — subsequent requests against it (including its MCP URL) return 404 — and any compute sandboxes attached to the session are shut down. Deleting an already-deleted session returns 404.