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.

Get a tool router session by ID

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

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

Returns the tools available in a tool router session with their complete schemas. This includes both meta tools and any preloaded app tools exposed by the session. 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.

Execute a tool within a tool router session

Executes a specific tool within a tool router session. This is the primary execution endpoint for both meta tools and app tools exposed by the session. The toolkit is automatically inferred from the tool slug. For app tools, the tool must belong to an allowed toolkit and must not be disabled in the session configuration. The endpoint validates permissions, resolves connected accounts when needed, and executes the tool with the session context. The top-level account field applies only to direct app tool execution in multi-account sessions. Meta/helper tools either ignore it or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.

Execute a meta tool within a tool router session

Executes a Composio meta tool (COMPOSIO_*) within a tool router session. This endpoint is kept for meta-tool compatibility; clients can also use the primary /execute endpoint.

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 given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.

Patch a tool router session config

Partially updates the configuration of an existing tool router session. Only the fields provided in the request body will be updated. Uses optimistic concurrency control to prevent lost updates. The previous config is stored in config history.