Skip to main content
POST

Authorizations

x-api-key
string
header
default:your-project-api-key
required

Your Composio project API key. Create or copy it from the Composio dashboard.

Body

application/json
user_id
string
required

The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address

Minimum string length: 1
Example:

"user_123456789"

toolkits
object

Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive. Experimentally, it can also list toolkits whose tools need approval, with or without a filter.

auth_configs
object

The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed

Example:
connected_accounts
object

Per-toolkit connected account override (single nano-ID). Each connected account must exist (not deleted or disabled) and belong to the same user_id as the session.

Example:
instant

Controls instant usage, subject to project permission and session toolkit and tool restrictions. False disables instant usage. Omission on create or an empty object enables it with charges hidden. On PATCH, omitted fields are preserved; an object re-enables a disabled setting.

Available options:
false
manage_connections
object

Configuration for connection management settings

tools
object

Tool-level configuration per toolkit. Allows you to enable, disable, or filter by tags for specific tools within each toolkit, and experimentally to list tools that need approval. Every tool slug must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.

tags

Session-wide tags for filtering tools. Array format is treated as an enabled list. Object format supports enable (a tool must have at least one) and disable (a tool must have none), and experimentally the tags whose tools need approval. If a toolkit sets tools.<toolkit>.tags, its tools use that object instead of this one.

Available options:
readOnlyHint,
createHint,
updateHint,
destructiveHint,
idempotentHint,
openWorldHint
Example:
workbench
object

Configuration for workbench behavior

proxy_execute
object

Configure proxy execute. Omitted from responses when not set. Session creation fails when enable is false and workbench.enable_proxy_execution is explicitly true.

multi_account
object

Configure multi-account behavior. When enabled, users can connect multiple accounts per toolkit.

experimental
object

Experimental features - not stable, may be modified or removed in future versions.

preload
object

Preload configuration for Composio tools. Controls which tools appear in session.tools and the MCP server tool list so the agent can call them directly without going through search first. Custom tools use preload on the custom tool/toolkit definition instead. Not supported when multi-account is enabled. Each preloaded tool adds to the agent context window, so keep the list at or under ~20 tools.

hooks
object[]

Hooks that run on this session's tool calls. A hook can block a call before it runs, or block its result before the agent sees it.

Maximum array length: 20

Response

Session successfully created. Returns the session ID and MCP server URL for the created session.

session_id
string<toolRouterSessionId>
required

The identifier of the session

Example:

"trs_1a2b3c4d5e6f"

mcp
object
required
tool_router_tools
string[]
required

List of available tools in this session

config
object
required

The session configuration including user, toolkits, and overrides

config_version
integer
required

Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control.

experimental
object

Experimental features including the generated system prompt. Only returned on session creation, not on GET.

warnings
object[]

Advisory list — the session exists and is usable, but the listed issues may warrant attention.

Example: