Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: document experimental Instant Tools for developers
Palash Kala committed
Sep 23, 2026 at 17:21 UTC
272c38bb436526c184065d25729aaf2efcb497ae
3 files changed
+109
docs/content/docs/instant-tools.mdx
new
+106
@@ -0,0 +1,106 @@
1
+---
2
+title: Instant Tools
3
+description: Use supported tools in a Session without asking every user to connect a provider account
4
+keywords: [Instant Tools, Sessions, premium usage, Composio-managed account]
5
+---
6
+
7
+Instant Tools let your Session run supported tools without an end-user provider connection. Composio supplies the provider account and charges eligible calls to your project's Composio balance.
8
+
9
+<Callout type="warning" title="Experimental access">
10
+ This feature requires a project setting that is not yet self-service. Email [support@composio.dev](mailto:support@composio.dev) to enable it for your project and confirm which tools and rates are available. Session configuration cannot override a project where the setting is off.
11
+</Callout>
12
+
13
+## Create a Session
14
+
15
+After your project is enabled, create a Session with an explicit `premium_usage` policy. This example makes Exa available to the Session and permits Composio-billed access for Exa:
16
+
17
+```bash
18
+curl --request POST \
19
+ --url https://backend.composio.dev/api/v3.1/tool_router/session \
20
+ --header "x-api-key: $COMPOSIO_API_KEY" \
21
+ --header "content-type: application/json" \
22
+ --data '{
23
+ "user_id": "user_123",
24
+ "toolkits": { "enable": ["exa"] },
25
+ "premium_usage": {
26
+ "toolkits": { "enable": ["exa"] },
27
+ "return_premium_charge": true
28
+ }
29
+ }'
30
+```
31
+
32
+The response includes a `session_id` and the effective `config`. Use the `session_id` for Session-scoped tool search and execution.
33
+
34
+The two toolkit lists control different things. Top-level `toolkits` controls which tools the Session can discover and run. `premium_usage.toolkits` controls which of those toolkits can use a Composio-billed route. A toolkit must pass *both* filters. An eligible toolkit can still contain tools that require a connected account.
35
+
36
+## Find and run a tool
37
+
38
+You can inspect a tool's input schema with the [get tool endpoint](/reference/v3/api-reference/tools/getToolsByToolSlug). For example:
39
+
40
+```bash
41
+curl --request GET \
42
+ --url https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH \
43
+ --header "x-api-key: $COMPOSIO_API_KEY"
44
+```
45
+
46
+Then execute a tool through the Session using the [Session execute endpoint](/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdExecute):
47
+
48
+```bash
49
+curl --request POST \
50
+ --url "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute" \
51
+ --header "x-api-key: $COMPOSIO_API_KEY" \
52
+ --header "content-type: application/json" \
53
+ --data '{
54
+ "tool_slug": "EXA_SEARCH",
55
+ "arguments": { "query": "Composio documentation" }
56
+ }'
57
+```
58
+
59
+Check the current tool schema before constructing `arguments`; fields can change with the tool version. The current tools API does *not* provide a structured Instant eligibility or price field. A tool appearing in a toolkit does not mean Composio-billed access is available for that tool. Confirm the supported tool list and rates during Experimental access.
60
+
61
+## Control billed access
62
+
63
+`premium_usage` is a Session policy. It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
64
+
65
+| Session value | Effect |
66
+|---|---|
67
+| Omitted or `{}` | Permits eligible Composio-billed tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
68
+| `false` | Disables Composio-billed access for that Session. Your own connected-account routes remain available. |
69
+| `{ "toolkits": { "enable": ["exa"] } }` | Permits billed access only for listed toolkits. Use `disable` instead to exclude selected toolkits. |
70
+| `{ "tools": { "exa": { "enable": ["EXA_SEARCH"] } } }` | Narrows billed access to selected tools within a toolkit. |
71
+| `{ "return_premium_charge": true }` | Requests the actual `premium_charge` in an eligible Session tool response. This changes charge visibility, not permission to spend. |
72
+
73
+For example, keep Exa and Firecrawl available, but permit billed access only for `EXA_SEARCH`:
74
+
75
+```json
76
+{
77
+ "user_id": "user_123",
78
+ "toolkits": { "enable": ["exa", "firecrawl"] },
79
+ "premium_usage": {
80
+ "toolkits": { "enable": ["exa"] },
81
+ "tools": { "exa": { "enable": ["EXA_SEARCH"] } }
82
+ }
83
+}
84
+```
85
+
86
+To stop Composio-billed access on an existing Session, use the [Session patch endpoint](/reference/v3/api-reference/tool-router/patchToolRouterSessionBySessionId):
87
+
88
+```bash
89
+curl --request PATCH \
90
+ --url "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID" \
91
+ --header "x-api-key: $COMPOSIO_API_KEY" \
92
+ --header "content-type: application/json" \
93
+ --data '{ "premium_usage": false }'
94
+```
95
+
96
+On patch, omitted `premium_usage` fields keep their existing values. Supplying an object after `false` enables this Session policy again, provided the project allows it.
97
+
98
+## Know which account runs the tool
99
+
100
+A Composio-managed account is a provider account held by Composio for specific tools. It is different from **Composio-managed auth**, where Composio supplies OAuth application credentials but your user still connects their own account. Composio-managed auth alone does not make a tool Instant.
101
+
102
+If you select a connected account explicitly, that route wins and does not fall back to Composio's account on failure. Otherwise, available user, shared, or developer connections take priority over a Composio-managed account. If the chosen tool is not supported by a Composio-managed account, it follows the normal connection flow.
103
+
104
+Composio-managed accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
105
+
106
+See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/v3/api-reference/tool-router/postToolRouterSession) for the complete request schema.
docs/content/docs/meta.json
+1
@@ -12,6 +12,7 @@
12
"---Core concepts---",
13
"how-composio-works",
14
"configuring-sessions",
15
+ "instant-tools",
16
"toolkits",
17
"authentication",
18
"triggers",
docs/lib/home-navigation.ts
+2
@@ -127,6 +127,7 @@ export const DOCS_PRODUCTS = {
127
'/docs/providers',
128
'/docs/how-composio-works',
129
'/docs/configuring-sessions',
130
+ '/docs/instant-tools',
131
'/docs/toolkits',
132
'/docs/authentication',
133
'/docs/triggers',
@@ -161,6 +162,7 @@ export const DOCS_PRODUCTS = {
162
links: [
163
{ url: '/docs/how-composio-works', label: 'What is a Session?' },
164
{ url: '/docs/configuring-sessions' },
165
+ { url: '/docs/instant-tools', label: 'Instant Tools (Experimental)' },
166
{ url: '/docs/sessions-via-mcp' },
167
],
168
},