@devries-cameron20 / composio Mirror · read-only / commits / cadbd463f
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 05:45 UTC

docs: clarify toolkit_versions default behavior in Get Tools API

When toolkit_versions is not specified, the API defaults to the base version (00000000_00) instead of latest, which returns fewer tools than what's shown on the platform UI. This is a common source of confusion for API users. Changes: - Add 'Default version behavior' section to toolkit-versioning.mdx - Add troubleshooting entry for 'API returning fewer tools than expected' - Add FAQ entry about API returning fewer tools than platform UI - Update fetching-tools.mdx callout to warn about version behavior - Add troubleshooting index entry linking to the new section - Enhance toolkit_versions parameter description in OpenAPI fetch script Co-Authored-By: Soham Ganatra <sohamganatra1@gmail.com>

Devin AI committed Mar 2, 2026 at 18:20 UTC cadbd463fddb5b31c901d2c222b73354b6d87327
6 files changed +74 -5
docs/content/docs/common-faq.mdx
+13
@@ -90,6 +90,19 @@ Composio toolkits are versioned using date-based identifiers (e.g., `20251027_00
90 This applies to direct tool execution only. Sessions with meta tools always use the latest version. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
91 </Accordion>
92
93 +<Accordion title="Why does the API return fewer tools than the platform UI?">
94 +When calling the Get Tools API (`GET /api/v3/tools`) without specifying a `toolkit_versions` parameter, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. The platform UI shows tools from the latest version.
95 +
96 +To get all available tools, pass `toolkit_versions=latest`:
97 +
98 +```bash
99 +curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
100 + -H 'x-api-key: YOUR_API_KEY'
101 +```
102 +
103 +For production use, pin to a specific version instead of `latest` to avoid breaking changes. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
104 +</Accordion>
105 +
106 <Accordion title="Can a user connect multiple accounts for the same app?">
107 Yes. For example, a user can connect both a personal and work Gmail account. Call `session.authorize()` multiple times for the same toolkit. Each session uses the most recently connected account by default, but you can pin a specific account when creating the session.
108
docs/content/docs/tools-direct/fetching-tools.mdx
+2 -2
@@ -238,6 +238,6 @@ const toolkitSearchRaw = await composio.tools.getRawComposioTools({
238 </Tab>
239 </Tabs>
240
241 -<Callout type="info">
242 -Use specific toolkit versions in production to prevent breaking changes. See [toolkit versioning](/docs/tools-direct/toolkit-versioning).
241 +<Callout type="warn">
242 +When no toolkit version is specified, the API returns tools from the base version (`00000000_00`), which may be fewer than what's available. Pass `toolkit_versions="latest"` or a specific version to get all tools. Never use `latest` in production. See [toolkit versioning](/docs/tools-direct/toolkit-versioning).
243 </Callout>
docs/content/docs/tools-direct/toolkit-versioning.mdx
+25 -3
@@ -21,6 +21,24 @@ You can also find the latest version for each toolkit on the [Toolkits](/toolkit
21 Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.
22 </Callout>
23
24 +## Default version behavior
25 +
26 +<Callout type="warn">
27 +When no version is specified, the API defaults to the base version (`00000000_00`), **not** the latest version. This means the response may contain fewer tools than what's shown on the [platform UI](https://platform.composio.dev). To get all available tools including ones added in newer versions, explicitly set `toolkit_versions` to `"latest"` or a specific version.
28 +</Callout>
29 +
30 +This applies to both the SDK and direct REST API calls:
31 +
32 +```bash
33 +# Without version — returns only tools from the base version
34 +curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive' \
35 + -H 'x-api-key: YOUR_API_KEY'
36 +
37 +# With version=latest — returns all tools including newer ones
38 +curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
39 + -H 'x-api-key: YOUR_API_KEY'
40 +```
41 +
42 ## Configuration methods
43
44 Configure toolkit versions using one of three methods:
@@ -118,15 +136,19 @@ Versions follow the format `YYYYMMDD_NN`:
136 - `NN`: Sequential release number
137
138 ```python
121 -# Production
139 +# Production — pin to a specific version
140 toolkit_versions = {"github": "20251027_00"}
141
124 -# Development
142 +# Development — always use the newest tools
143 toolkit_versions = {"github": "latest"}
144 ```
145
146 <Callout type="warn">
129 -Never use `latest` in production. It can introduce breaking changes.
147 +Never use `latest` in production. It can introduce breaking changes. Pin to a specific version instead.
148 +</Callout>
149 +
150 +<Callout type="info">
151 +If you omit `toolkit_versions` entirely, the API uses the base version (`00000000_00`). This is the oldest version and may not include all tools available for a toolkit. Always specify a version explicitly.
152 </Callout>
153
154 ## Version resolution order
docs/content/docs/troubleshooting/index.mdx
+6
@@ -47,6 +47,12 @@ Go to the [dashboard](https://platform.composio.dev) and navigate to **Active Tr
47 See [Troubleshooting triggers](/docs/troubleshooting/triggers#reporting-issues) for a screenshot.
48 </Accordion>
49
50 +<Accordion title="Why does the API return fewer tools than the platform UI?">
51 +The Get Tools API defaults to the base toolkit version (`00000000_00`) when `toolkit_versions` is not specified. Pass `toolkit_versions=latest` to get all available tools.
52 +
53 +See [Troubleshooting tools](/docs/troubleshooting/tools#api-returning-fewer-tools-than-expected) for details.
54 +</Accordion>
55 +
56 </Accordions>
57
58 ## Quick links
docs/content/docs/troubleshooting/tools.mdx
+15
@@ -31,6 +31,21 @@ Verify the connected account has necessary permissions:
31 - **Paid accounts**: Certain toolkits need paid subscriptions
32 - Example: MS Teams requires Microsoft 365 account + Azure AD tenant
33
34 +## API returning fewer tools than expected
35 +
36 +If the Get Tools API (`GET /api/v3/tools`) returns fewer tools than what's shown on the [platform UI](https://platform.composio.dev), you likely need to specify a toolkit version.
37 +
38 +When `toolkit_versions` is not provided, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. Tools added in later versions won't appear.
39 +
40 +To get all available tools, pass `toolkit_versions=latest`:
41 +
42 +```bash
43 +curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
44 + -H 'x-api-key: YOUR_API_KEY'
45 +```
46 +
47 +For production use, pin to a specific version instead of `latest`. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
48 +
49 ## Tool not working
50
51 - Check [tool-specific documentation](/toolkits) for requirements
docs/scripts/fetch-openapi.mjs
+13
@@ -117,6 +117,19 @@ async function fetchAndFilterSpec() {
117 console.log(`Removed ${removedCount} endpoints/operations`);
118 console.log(`Final spec has ${Object.keys(filteredPaths).length} paths`);
119
120 + // Enhance toolkit_versions parameter description for clarity
121 + for (const methods of Object.values(spec.paths)) {
122 + for (const operation of Object.values(methods)) {
123 + if (operation.parameters) {
124 + for (const param of operation.parameters) {
125 + if (param.name === 'toolkit_versions') {
126 + param.description = 'Toolkit version specification. **When not specified, defaults to the base version (`00000000_00`), which may return fewer tools than the latest version.** Use `"latest"` to get all available tools, or use bracket notation for specific versions per toolkit (e.g., `toolkit_versions[gmail]=20250930_00`). For production, pin to a specific version instead of `"latest"` to avoid breaking changes.';
127 + }
128 + }
129 + }
130 + }
131 + }
132 +
133 // Normalize overly complex anyOf/oneOf schemas (e.g., connection_data with 68 object variants)
134 // Merges similar object schemas into a single object with all properties
135 let unionNormalizedCount = 0;