@devries-cameron20 / composio-1 / commits / 272c38bb4
Fork 0

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 },