Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Versioning docs

Sushmithamallesh3ad7f40a4059
diff --git a/fern/docs.yml b/fern/docs.yml
index f38c2d480..8e8478d4f 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -135,6 +135,9 @@ navigation:
- page: Custom tools
path: pages/dist/tool-calling/custom-tools.mdx
slug: custom-tools
+ - page: Toolkit Versioning
+ path: pages/dist/tool-calling/toolkit-versioning.mdx
+ slug: toolkit-versioning
- section: Authentication
icon: lock
skip-slug: true
@@ -188,9 +191,18 @@ navigation:
- page: Debugging Info
path: pages/dist/debugging-info.mdx
slug: resources/debugging-info
- - page: Migration Guide
- path: pages/dist/migration-guide.mdx
- slug: migration
+ - section: Migration Guides
+ slug: migration-guide
+ contents:
+ - page: Overview
+ path: pages/dist/migration-guide/index.mdx
+ slug: overview
+ - page: New SDK Migration
+ path: pages/dist/migration-guide/new-sdk.mdx
+ slug: new-sdk
+ - page: Toolkit Versioning Migration
+ path: pages/dist/migration-guide/toolkit-versioning.mdx
+ slug: toolkit-versioning
- section: Troubleshooting
slug: troubleshooting
contents:
diff --git a/fern/pages/src/migration-guide/index.mdx b/fern/pages/src/migration-guide/index.mdx
new file mode 100644
index 000000000..c9d9d6dc7
--- /dev/null
+++ b/fern/pages/src/migration-guide/index.mdx
@@ -0,0 +1,25 @@
+---
+title: Migration guides
+subtitle: Guides for migrating to newer versions of Composio
+image: "https://og.composio.dev/api/og?title=Migration%20guides"
+keywords: "migration, upgrade, sdk, versioning"
+hide-nav-links: false
+---
+
+Find the appropriate migration guide for your use case:
+
+## Available migration guides
+
+<AccordionGroup>
+ <Accordion title="New SDK migration">
+ Migrate from the old Composio SDK to the new next-generation SDK, including breaking changes, new features, and updated APIs.
+
+ [View SDK migration guide →](/resources/migration-guide/new-sdk)
+ </Accordion>
+
+ <Accordion title="Toolkit versioning migration">
+ Migrate to the new toolkit versioning system introduced on October 22, 2025.
+
+ [View versioning migration guide →](/resources/migration-guide/toolkit-versioning)
+ </Accordion>
+</AccordionGroup>
\ No newline at end of file
diff --git a/fern/pages/src/migration-guide.mdx b/fern/pages/src/migration-guide/new-sdk.mdx
similarity index 99%
rename from fern/pages/src/migration-guide.mdx
rename to fern/pages/src/migration-guide/new-sdk.mdx
index 57a0c5019..bcabf1e50 100644
--- a/fern/pages/src/migration-guide.mdx
+++ b/fern/pages/src/migration-guide/new-sdk.mdx
@@ -1,9 +1,9 @@
---
-title: Our next generation SDKs
+title: New SDK migration
subtitle: Learn more about Composio's next generation SDKs and how to migrate
-image: "https://og.composio.dev/api/og?title=Our%20next%20generation%20SDKs" # image for socials
-keywords: ''
-hide-nav-links: true
+image: "https://og.composio.dev/api/og?title=New%20SDK%20migration"
+keywords: 'sdk, migration, next generation, upgrade'
+hide-nav-links: false
---
In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.
diff --git a/fern/pages/src/migration-guide/toolkit-versioning.mdx b/fern/pages/src/migration-guide/toolkit-versioning.mdx
new file mode 100644
index 000000000..d38f94bc1
--- /dev/null
+++ b/fern/pages/src/migration-guide/toolkit-versioning.mdx
@@ -0,0 +1,134 @@
+---
+title: Toolkit versioning migration
+subtitle: Migrate to the new toolkit versioning system
+image: "https://og.composio.dev/api/og?title=Toolkit%20versioning%20migration"
+keywords: "toolkit versioning, migration, breaking changes"
+hide-nav-links: false
+---
+
+Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.
+
+## Breaking change
+
+Manual tool execution now requires explicit version specification. The `tools.execute()` method will fail without a version.
+
+### Before (will fail)
+
+<CodeGroup>
+```python Python
+# Raises ToolVersionRequiredError
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {"user_id": "user-123", "arguments": {...}}
+)
+```
+
+```typescript TypeScript
+// Throws ComposioToolVersionRequiredError
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {...}
+});
+```
+</CodeGroup>
+
+### After (required)
+
+Choose one of three migration strategies:
+
+#### Option 1: Configure version at SDK level
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/sdk-initialization.py"
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts"
+ title="TypeScript"
+/>
+</CodeGroup>
+
+#### Option 2: Pass version with each execution
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/per-execution-override.py"
+ startLine={5}
+ endLine={16}
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts"
+ startLine={5}
+ endLine={14}
+ title="TypeScript"
+/>
+</CodeGroup>
+
+#### Option 3: Use environment variables
+
+```bash
+export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
+```
+
+Then execute normally:
+
+<CodeGroup>
+```python Python
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {"user_id": "user-123", "arguments": {...}}
+)
+```
+
+```typescript TypeScript
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {...}
+});
+```
+</CodeGroup>
+
+## Migration checklist
+
+1. **Audit your code**: Find all `tools.execute()` calls in your codebase
+2. **Choose a strategy**: Select one of the three options above based on your needs
+3. **Test thoroughly**: Verify tools work correctly with pinned versions
+4. **Deploy gradually**: Roll out changes incrementally to minimize risk
+
+## Temporary workaround
+
+During migration, you can temporarily skip version checks (not recommended for production):
+
+<CodeGroup>
+```python Python
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {...}
+ },
+ dangerously_skip_version_check=True
+)
+```
+
+```typescript TypeScript
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {...},
+ dangerouslySkipVersionCheck: true
+});
+```
+</CodeGroup>
+
+<Warning>
+The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never use in production.
+</Warning>
+
+## Next steps
+
+For complete documentation on toolkit versioning, including best practices and advanced configuration, see [Toolkit versioning](/docs/toolkit-versioning).
\ No newline at end of file
diff --git a/fern/pages/src/tool-calling/executing-tools.mdx b/fern/pages/src/tool-calling/executing-tools.mdx
index 9c9dcc129..7892214fa 100644
--- a/fern/pages/src/tool-calling/executing-tools.mdx
+++ b/fern/pages/src/tool-calling/executing-tools.mdx
@@ -63,11 +63,22 @@ In case you just want to call a tool without using any framework or LLM provider
tab](https://platform.composio.dev?next_page=/auth-configs) → Select your toolkit → Tools &
Triggers → Select the tool to see its required and optional parameters, types, and descriptions.
</Tip>
+
<CodeGroup>
- <SnippetCode src="fern/snippets/tool-calling/python/direct-tool-call.py" title="Python" />
- <SnippetCode src="fern/snippets/tool-calling/typescript/direct-tool-call.ts" title="TypeScript" />
+ <SnippetCode
+ src="fern/snippets/tool-calling/python/direct-tool-call.py"
+ title="Python"
+ />
+ <SnippetCode
+ src="fern/snippets/tool-calling/typescript/direct-tool-call.ts"
+ title="TypeScript"
+ />
</CodeGroup>
+<Note>
+The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/toolkit-versioning) for all configuration options.
+</Note>
+
### Proxy Execute -- Manually calling toolkit APIs
You can proxy requests to any supported toolkit API and let Composio inject the **authentication state**. This is useful when you need an API endpoint that isn't available as a predefined tool.
diff --git a/fern/pages/src/tool-calling/fetching-tools.mdx b/fern/pages/src/tool-calling/fetching-tools.mdx
index ce0ea5db8..458efac96 100644
--- a/fern/pages/src/tool-calling/fetching-tools.mdx
+++ b/fern/pages/src/tool-calling/fetching-tools.mdx
@@ -94,6 +94,10 @@ const tools = await composio.tools.get(userId, {
```
</CodeGroup>
+## Tool versions
+
+You can configure toolkit versions at SDK initialization to ensure consistent tool behavior across environments. When fetching tools, you can also [inspect which version each tool is using](/docs/toolkit-versioning#inspect-current-versions).
+
## Filtering by tool
You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools [here](/tools) to view and inspect the tools for each toolkit.
diff --git a/fern/pages/src/tool-calling/toolkit-versioning.mdx b/fern/pages/src/tool-calling/toolkit-versioning.mdx
new file mode 100644
index 000000000..86bb2d868
--- /dev/null
+++ b/fern/pages/src/tool-calling/toolkit-versioning.mdx
@@ -0,0 +1,118 @@
+---
+title: Toolkit versioning
+image: "https://og.composio.dev/api/og?title=Toolkit%20versioning"
+keywords: "toolkit versioning, tool version, version pinning, stable tools"
+subtitle: "Pin specific tool versions for consistent behavior in production"
+hide-nav-links: false
+---
+
+Toolkit versioning ensures your tools behave consistently across deployments. You can pin specific versions in production, test new releases in development, and roll back when needed.
+
+<Note>
+Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.
+</Note>
+
+## Configuration methods
+
+Configure toolkit versions using one of three methods:
+
+### SDK initialization
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/sdk-initialization.py"
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts"
+ title="TypeScript"
+/>
+</CodeGroup>
+
+### Environment variables
+
+```bash
+# Set versions for specific toolkits
+export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
+export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
+export COMPOSIO_TOOLKIT_VERSION_GMAIL="20250115_00"
+```
+
+### Per-execution override
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/per-execution-override.py"
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts"
+ title="TypeScript"
+/>
+</CodeGroup>
+
+## Version format
+
+Versions follow the format `YYYYMMDD_NN`:
+- `YYYYMMDD`: Release date
+- `NN`: Sequential release number
+
+```python
+# Production
+toolkit_versions = {"github": "20250116_00"}
+
+# Development
+toolkit_versions = {"github": "latest"}
+```
+
+<Warning>
+Never use `latest` in production. It can introduce breaking changes.
+</Warning>
+
+## Version resolution order
+
+1. Per-execution version (highest priority)
+2. SDK initialization version
+3. Environment variable (toolkit-specific)
+
+## Managing versions
+
+### List available versions
+
+Check what versions are available for a toolkit:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/manage-versions.py"
+ startLine={8}
+ endLine={11}
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/manage-versions.ts"
+ startLine={8}
+ endLine={12}
+ title="TypeScript"
+/>
+</CodeGroup>
+
+### Inspect current versions
+
+Check which version your tools are actually using:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/manage-versions.py"
+ startLine={13}
+ endLine={16}
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/manage-versions.ts"
+ startLine={14}
+ endLine={20}
+ title="TypeScript"
+/>
+</CodeGroup>
+
+
diff --git a/fern/snippets/tool-calling/python/direct-tool-call.py b/fern/snippets/tool-calling/python/direct-tool-call.py
index 1d568a87d..8658eacd0 100644
--- a/fern/snippets/tool-calling/python/direct-tool-call.py
+++ b/fern/snippets/tool-calling/python/direct-tool-call.py
@@ -1,7 +1,11 @@
from composio import Composio
user_id = "user-k7334"
-composio = Composio(api_key="your_composio_key")
+# Configure toolkit versions at SDK level
+composio = Composio(
+ api_key="your_composio_key",
+ toolkit_versions={"github": "20250116_00"}
+)
# Find available arguments for any tool in the Composio dashboard
result = composio.tools.execute(
diff --git a/fern/snippets/tool-calling/typescript/direct-tool-call.ts b/fern/snippets/tool-calling/typescript/direct-tool-call.ts
index 3f8057e62..df5c9e725 100644
--- a/fern/snippets/tool-calling/typescript/direct-tool-call.ts
+++ b/fern/snippets/tool-calling/typescript/direct-tool-call.ts
@@ -1,7 +1,11 @@
import { Composio } from "@composio/core";
const userId = "user-k7334";
-const composio = new Composio({apiKey: "your_composio_key"});
+// Configure toolkit versions at SDK level
+const composio = new Composio({
+ apiKey: "your_composio_key",
+ toolkitVersions: { github: "20250116_00" }
+});
// Find available arguments for any tool in the Composio dashboard
const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
diff --git a/fern/snippets/tool-calling/versioning/python/manage-versions.py b/fern/snippets/tool-calling/versioning/python/manage-versions.py
new file mode 100644
index 000000000..7b51f1be3
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/manage-versions.py
@@ -0,0 +1,16 @@
+from composio import Composio
+
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={"github": "20250116_00"}
+)
+
+# List available versions for a toolkit
+versions = composio.tools.get_toolkit_versions("github")
+for version in versions[:3]:
+ print(f"Version: {version['version']} - Status: {version['status']}")
+
+# Fetch tools and inspect their versions
+tools = composio.tools.get("user-123", toolkits=["github"])
+for tool in tools[:3]:
+ print(f"{tool.slug}: v{tool.toolkit_version}")
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/per-execution-override.py b/fern/snippets/tool-calling/versioning/python/per-execution-override.py
new file mode 100644
index 000000000..aa6658c27
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/per-execution-override.py
@@ -0,0 +1,16 @@
+from composio import Composio
+
+composio = Composio(api_key="YOUR_API_KEY")
+
+# Specify version directly in execute call
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Critical fix"
+ },
+ "toolkit_version": "20250116_00" # Version for this execution
+ }
+)
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/sdk-initialization.py b/fern/snippets/tool-calling/versioning/python/sdk-initialization.py
new file mode 100644
index 000000000..a391dd09f
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/sdk-initialization.py
@@ -0,0 +1,11 @@
+from composio import Composio
+
+# Pin specific versions for each toolkit
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={
+ "github": "20250116_00",
+ "slack": "20250115_01",
+ "gmail": "20250115_00"
+ }
+)
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/manage-versions.ts b/fern/snippets/tool-calling/versioning/typescript/manage-versions.ts
new file mode 100644
index 000000000..1685fffeb
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/manage-versions.ts
@@ -0,0 +1,20 @@
+import { Composio } from "@composio/core";
+
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: { github: "20250116_00" }
+});
+
+// List available versions for a toolkit
+const versions = await composio.tools.getToolkitVersions("github");
+versions.slice(0, 3).forEach(version => {
+ console.log(`Version: ${version.version} - Status: ${version.status}`);
+});
+
+// Fetch tools and inspect their versions
+const tools = await composio.tools.get("user-123", {
+ toolkits: ["github"]
+});
+tools.slice(0, 3).forEach(tool => {
+ console.log(`${tool.slug}: v${tool.toolkitVersion}`);
+});
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts b/fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts
new file mode 100644
index 000000000..221017717
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts
@@ -0,0 +1,14 @@
+import { Composio } from "@composio/core";
+
+const composio = new Composio({ apiKey: "YOUR_API_KEY" });
+
+// Specify version directly in execute call
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Critical fix"
+ },
+ toolkitVersion: "20250116_00" // Version for this execution
+});
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts b/fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts
new file mode 100644
index 000000000..0e11d1f8f
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts
@@ -0,0 +1,11 @@
+import { Composio } from "@composio/core";
+
+// Pin specific versions for each toolkit
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: {
+ github: "20250116_00",
+ slack: "20250115_01",
+ gmail: "20250115_00"
+ }
+});
\ No newline at end of file