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

Sushmithamalleshe5e9a7446ea9
diff --git a/fern/pages/src/migration-guide.mdx b/fern/pages/src/migration-guide.mdx
index 57a0c5019..ae240e6b1 100644
--- a/fern/pages/src/migration-guide.mdx
+++ b/fern/pages/src/migration-guide.mdx
@@ -205,6 +205,93 @@ To examine the raw schema definition of a tool for understanding input/output pa
/>
</CodeGroup>
+### Toolkit versioning
+
+As of October 22, 2025, Composio enforces toolkit versioning to ensure consistent tool behavior across environments. This is a breaking change for manual tool execution.
+
+#### Version requirement for manual execution
+
+Manual tool execution now requires explicit version specification:
+
+<CodeGroup>
+```python Python
+# Will fail without version (breaking change)
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {"user_id": "user-123", "arguments": {...}}
+)
+
+# Option 1: Configure version at SDK level
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={"github": "20250116_00"}
+)
+
+# Option 2: Pass version with execution
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {...},
+ "toolkit_version": "20250116_00"
+ }
+)
+
+# Option 3: Skip version check (not recommended)
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {...},
+ "dangerously_skip_version_check": True
+ }
+)
+```
+
+```typescript TypeScript
+// Will fail without version (breaking change)
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {...}
+});
+
+// Option 1: Configure version at SDK level
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: { github: "20250116_00" }
+});
+
+// Option 2: Pass version with execution
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {...},
+ toolkitVersion: "20250116_00"
+});
+
+// Option 3: Skip version check (not recommended)
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {...},
+ dangerouslySkipVersionCheck: true
+});
+```
+</CodeGroup>
+
+#### Migration steps
+
+1. **Audit your code**: Find all `tools.execute()` calls
+2. **Choose a strategy**:
+ - Set toolkit versions globally in SDK initialization (recommended)
+ - Add version parameter to each execute call
+ - Use environment variables for deployment configuration
+3. **Test thoroughly**: Verify tools work with pinned versions
+4. **Deploy gradually**: Roll out changes incrementally
+
+For complete documentation, see [Toolkit versioning](/tool-calling/toolkit-versioning).
+
### Executing tools
Tool execution remains largely unchanged, with `user_id` now explicitly required.
@@ -586,7 +673,7 @@ For development, you can also [listen to triggers through the SDK](/docs/using-t
/>
</CodeGroup>
-## 🚧 Coming Soon
+## Coming Soon
### Local tools
diff --git a/fern/pages/src/tool-calling/executing-tools.mdx b/fern/pages/src/tool-calling/executing-tools.mdx
index 9c9dcc129..a7cb22fc5 100644
--- a/fern/pages/src/tool-calling/executing-tools.mdx
+++ b/fern/pages/src/tool-calling/executing-tools.mdx
@@ -58,14 +58,84 @@ Composio provides support for frameworks like this by making sure the tools are
In case you just want to call a tool without using any framework or LLM provider, you can use the `execute` method directly.
+<Warning>
+As of October 22, 2025, manual tool execution requires explicit version specification. Either configure toolkit versions in your SDK initialization or pass the version with each execution. See [toolkit versioning](/tool-calling/toolkit-versioning) for details.
+</Warning>
+
<Tip icon="lightbulb">
**Finding tool arguments**: In the [Auth Configs
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" />
+```python Python
+# Method 1: Configure version at SDK level
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={"github": "20250116_00"}
+)
+
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "composio",
+ "owner": "composiohq",
+ "title": "Bug Report",
+ "body": "Issue description"
+ }
+ }
+)
+
+# Method 2: Pass version with execution
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "composio",
+ "owner": "composiohq",
+ "title": "Bug Report",
+ "body": "Issue description"
+ },
+ "toolkit_version": "20250116_00"
+ }
+)
+```
+
+```typescript TypeScript
+// Method 1: Configure version at SDK level
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: { github: "20250116_00" }
+});
+
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "composio",
+ owner: "composiohq",
+ title: "Bug Report",
+ body: "Issue description"
+ }
+});
+
+// Method 2: Pass version with execution
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "composio",
+ owner: "composiohq",
+ title: "Bug Report",
+ body: "Issue description"
+ },
+ toolkitVersion: "20250116_00"
+});
+```
</CodeGroup>
### Proxy Execute -- Manually calling toolkit APIs
diff --git a/fern/pages/src/tool-calling/fetching-tools.mdx b/fern/pages/src/tool-calling/fetching-tools.mdx
index ce0ea5db8..2528c1047 100644
--- a/fern/pages/src/tool-calling/fetching-tools.mdx
+++ b/fern/pages/src/tool-calling/fetching-tools.mdx
@@ -94,6 +94,58 @@ const tools = await composio.tools.get(userId, {
```
</CodeGroup>
+## Fetching versioned tools
+
+Control which version of tools you fetch by specifying toolkit versions. This ensures consistent tool behavior across different environments.
+
+<CodeGroup>
+```python Python maxLines=60 wordWrap
+# Fetch tools with specific versions
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={
+ "github": "20250116_00",
+ "slack": "20250115_01"
+ }
+)
+
+tools = composio.tools.get(
+ user_id,
+ toolkits=["GITHUB", "SLACK"]
+)
+
+# Inspect tool version
+for tool in tools:
+ print(f"Tool: {tool.slug}")
+ print(f"Version: {tool.toolkit_version}")
+```
+
+```typescript TypeScript maxLines=60 wordWrap
+// Fetch tools with specific versions
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: {
+ github: "20250116_00",
+ slack: "20250115_01"
+ }
+});
+
+const tools = await composio.tools.get(userId, {
+ toolkits: ["GITHUB", "SLACK"]
+});
+
+// Inspect tool version
+tools.forEach(tool => {
+ console.log(`Tool: ${tool.slug}`);
+ console.log(`Version: ${tool.toolkitVersion}`);
+});
+```
+</CodeGroup>
+
+<Note>
+Tools fetched with specific versions will maintain consistent schemas and behavior. Learn more about [toolkit versioning](/tool-calling/toolkit-versioning).
+</Note>
+
## 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..d7ee8ed5d
--- /dev/null
+++ b/fern/pages/src/tool-calling/toolkit-versioning.mdx
@@ -0,0 +1,304 @@
+---
+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, predictable 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 easily when needed.
+
+## Quick start
+
+Configure toolkit versions using one of three methods, listed in order of precedence:
+
+### Method 1: SDK initialization (Recommended)
+
+Set versions when initializing the SDK. This applies to all tool operations.
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/sdk-initialization.py"
+ title="Python"
+ startLine={1}
+ endLine={16}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts"
+ title="TypeScript"
+ startLine={1}
+ endLine={15}
+/>
+</CodeGroup>
+
+### Method 2: Environment variables
+
+Set toolkit versions through environment variables. Useful for deployment configurations.
+
+```bash
+# Set versions for specific toolkits
+export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
+export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
+
+# Or set one version for all toolkits
+export COMPOSIO_TOOLKIT_VERSION="20250116_00"
+```
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/environment-variables.py"
+ title="Python"
+ startLine={11}
+ endLine={18}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/environment-variables.ts"
+ title="TypeScript"
+ startLine={11}
+ endLine={18}
+/>
+</CodeGroup>
+
+### Method 3: Per-execution override
+
+Override versions for specific tool executions. Takes precedence over SDK and environment settings.
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/per-execution-override.py"
+ title="Python"
+ startLine={11}
+ endLine={21}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts"
+ title="TypeScript"
+ startLine={11}
+ endLine={19}
+/>
+</CodeGroup>
+
+## Version formats
+
+### Version identifiers
+
+Toolkit versions follow the format `YYYYMMDD_NN`:
+- `YYYYMMDD`: Release date
+- `NN`: Sequential release number for that day
+
+```python
+# Production: Use specific version
+toolkit_versions = {
+ "github": "20250116_00" # Released January 16, 2025, first version
+}
+
+# Development: Use latest
+toolkit_versions = {
+ "github": "latest" # Always use newest version
+}
+```
+
+### Version resolution
+
+Versions are resolved in this order:
+1. **Per-execution version** (if specified)
+2. **SDK initialization version** (if configured)
+3. **Environment variable** for specific toolkit
+4. **Global environment variable** (applies to all)
+5. **Default**: `latest`
+
+<Warning>
+Never use `latest` in production. It can introduce breaking changes without warning.
+</Warning>
+
+## Configuration patterns
+
+### Multi-environment setup
+
+Manage different versions across development, staging, and production environments:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/multi-environment.py"
+ title="Python"
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/multi-environment.ts"
+ title="TypeScript"
+/>
+</CodeGroup>
+
+### CI/CD pipeline
+
+```yaml
+# .github/workflows/deploy.yml
+env:
+ COMPOSIO_TOOLKIT_VERSION_GITHUB: "20250110_00"
+ COMPOSIO_TOOLKIT_VERSION_SLACK: "20250110_00"
+ COMPOSIO_TOOLKIT_VERSION_GMAIL: "20250109_00"
+```
+
+## Managing versions
+
+### List available versions
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/list-versions.py"
+ title="Python"
+ startLine={5}
+ endLine={14}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/list-versions.ts"
+ title="TypeScript"
+ startLine={5}
+ endLine={14}
+/>
+</CodeGroup>
+
+### Test new versions
+
+Test updates in isolated environments before production deployment:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/test-new-version.py"
+ title="Python"
+ startLine={4}
+ endLine={29}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/test-new-version.ts"
+ title="TypeScript"
+ startLine={3}
+ endLine={40}
+/>
+</CodeGroup>
+
+### Roll back versions
+
+If issues arise, immediately revert to a previous stable version:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/rollback.py"
+ title="Python"
+ startLine={4}
+ endLine={22}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/rollback.ts"
+ title="TypeScript"
+ startLine={3}
+ endLine={22}
+/>
+</CodeGroup>
+
+## Breaking changes
+
+### Manual execution requires version
+
+As of October 22, 2025, manual tool execution requires explicit version specification:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/python/breaking-changes.py"
+ title="Python"
+ startLine={21}
+ endLine={61}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/versioning/typescript/breaking-changes.ts"
+ title="TypeScript"
+ startLine={20}
+ endLine={54}
+/>
+</CodeGroup>
+
+<Warning>
+The `dangerouslySkipVersionCheck` flag bypasses version validation. Use only during migration or debugging.
+</Warning>
+
+### Migration checklist
+
+1. **Audit current usage**: Identify all `tools.execute()` calls
+2. **Choose strategy**:
+ - Set toolkit versions in SDK initialization (recommended)
+ - Add version parameter to each execute call
+ - Use environment variables for deployment config
+3. **Test in staging**: Verify tools work with pinned versions
+4. **Deploy gradually**: Roll out to production incrementally
+5. **Monitor errors**: Watch for version-related failures
+
+## Best practices
+
+### Version pinning strategy
+
+```python
+# Development: Latest for rapid iteration
+dev_versions = {"github": "latest", "slack": "latest"}
+
+# Staging: Test specific new versions
+staging_versions = {"github": "20250116_00", "slack": "20250115_00"}
+
+# Production: Pin stable versions
+prod_versions = {"github": "20250110_00", "slack": "20250110_00"}
+```
+
+### Update workflow
+
+1. **Development**: Test with `latest`
+2. **Staging**: Pin specific version for testing
+3. **Validation**: Run automated tests
+4. **Production**: Deploy tested version
+5. **Monitor**: Track errors and performance
+
+
+## Reference
+
+### SDK parameters
+
+<CodeGroup>
+```python Python
+Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={
+ "toolkit_name": "version" # Dict[str, str]
+ }
+)
+```
+
+```typescript TypeScript
+new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: {
+ toolkitName: "version" // Record<string, string>
+ }
+})
+```
+</CodeGroup>
+
+### Environment variables
+
+```bash
+# Specific toolkit version
+COMPOSIO_TOOLKIT_VERSION_[TOOLKIT_NAME]="version"
+
+# Global version (all toolkits)
+COMPOSIO_TOOLKIT_VERSION="version"
+
+# Examples
+COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
+COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
+COMPOSIO_TOOLKIT_VERSION="20250110_00"
+```
+
+### Error codes
+
+| Error | Description | Solution |
+|-------|-------------|----------|
+| `TOOLKIT_VERSION_REQUIRED` | Manual execution without version | Specify toolkit_version parameter |
+| `INVALID_TOOLKIT_VERSION` | Version format incorrect | Use YYYYMMDD_NN format |
+| `VERSION_NOT_FOUND` | Specified version doesn't exist | Check available versions |
+| `TOOLKIT_NOT_VERSIONED` | Toolkit doesn't support versioning | Contact support |
diff --git a/fern/snippets/tool-calling/versioning/python/breaking-changes.py b/fern/snippets/tool-calling/versioning/python/breaking-changes.py
new file mode 100644
index 000000000..e3663ff06
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/breaking-changes.py
@@ -0,0 +1,66 @@
+from composio import Composio
+
+composio = Composio(api_key="YOUR_API_KEY")
+
+# ❌ This will fail without version specification (after October 22, 2025)
+try:
+ result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Bug report",
+ "body": "Issue description"
+ }
+ }
+ )
+except Exception as e:
+ print(f"Error: {e}")
+ print("Manual execution requires toolkit version")
+
+# βœ… Solution 1: Specify version in execution
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Bug report",
+ "body": "Issue description"
+ },
+ "toolkit_version": "20250116_00"
+ }
+)
+
+# βœ… Solution 2: Configure version at SDK level
+composio_with_version = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={"github": "20250116_00"}
+)
+
+result = composio_with_version.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Bug report",
+ "body": "Issue description"
+ }
+ }
+)
+
+# ⚠️ Emergency escape hatch (not recommended for production)
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Bug report",
+ "body": "Issue description"
+ },
+ "dangerously_skip_version_check": True
+ }
+)
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/environment-variables.py b/fern/snippets/tool-calling/versioning/python/environment-variables.py
new file mode 100644
index 000000000..c1e8fef4b
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/environment-variables.py
@@ -0,0 +1,22 @@
+import os
+from composio import Composio
+
+# Set environment variables before running your application
+# export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
+# export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
+
+# Or set a global version for all toolkits
+# export COMPOSIO_TOOLKIT_VERSION="20250116_00"
+
+# SDK automatically reads environment variables
+composio = Composio(api_key="YOUR_API_KEY")
+
+# Tools will use versions from environment variables
+tools = composio.tools.get(
+ user_id="user-123",
+ toolkits=["github", "slack"]
+)
+
+# Check which versions are being used
+for tool in tools:
+ print(f"Tool: {tool.slug}, Version: {tool.toolkit_version}")
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/list-versions.py b/fern/snippets/tool-calling/versioning/python/list-versions.py
new file mode 100644
index 000000000..f12107f18
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/list-versions.py
@@ -0,0 +1,30 @@
+from composio import Composio
+from datetime import datetime
+
+composio = Composio(api_key="YOUR_API_KEY")
+
+# Get all available versions for a toolkit
+versions = composio.tools.get_toolkit_versions("github")
+
+# Display version information
+for version in versions:
+ print(f"Version: {version['version']}")
+ print(f"Released: {version['created_at']}")
+ print(f"Status: {version['status']}")
+ print("-" * 40)
+
+# Find the latest stable version
+stable_versions = [v for v in versions if v['status'] == 'stable']
+if stable_versions:
+ latest_stable = stable_versions[0]
+ print(f"Latest stable version: {latest_stable['version']}")
+
+# Find versions released in the last 7 days
+recent_versions = []
+for version in versions:
+ release_date = datetime.fromisoformat(version['created_at'])
+ days_ago = (datetime.now() - release_date).days
+ if days_ago <= 7:
+ recent_versions.append(version)
+
+print(f"Versions released in last 7 days: {len(recent_versions)}")
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/multi-environment.py b/fern/snippets/tool-calling/versioning/python/multi-environment.py
new file mode 100644
index 000000000..4ce03126d
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/multi-environment.py
@@ -0,0 +1,33 @@
+import os
+from composio import Composio
+
+# Get current environment from environment variable
+env = os.getenv("ENVIRONMENT", "development")
+
+# Define version configurations for each environment
+version_configs = {
+ "development": {
+ "github": "latest",
+ "slack": "latest",
+ "gmail": "latest"
+ },
+ "staging": {
+ "github": "20250116_00", # Test new GitHub version
+ "slack": "20250110_00", # Keep stable Slack version
+ "gmail": "20250110_00"
+ },
+ "production": {
+ "github": "20250110_00", # Stable, tested version
+ "slack": "20250110_00", # Stable, tested version
+ "gmail": "20250109_00" # Stable, tested version
+ }
+}
+
+# Initialize Composio with environment-specific versions
+composio = Composio(
+ api_key=os.getenv("COMPOSIO_API_KEY"),
+ toolkit_versions=version_configs[env]
+)
+
+print(f"Environment: {env}")
+print(f"Toolkit versions: {version_configs[env]}")
\ 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..740f94af6
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/per-execution-override.py
@@ -0,0 +1,33 @@
+from composio import Composio
+
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={
+ "github": "20250110_00" # Default version
+ }
+)
+
+# Override version for a single execution
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Bug report",
+ "body": "Description here"
+ },
+ "toolkit_version": "20250115_00" # Override to different version
+ }
+)
+
+# This execution uses the SDK default version
+result2 = composio.tools.execute(
+ "GITHUB_LIST_ISSUES",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo"
+ }
+ }
+)
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/rollback.py b/fern/snippets/tool-calling/versioning/python/rollback.py
new file mode 100644
index 000000000..6863f309d
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/rollback.py
@@ -0,0 +1,61 @@
+from composio import Composio
+import os
+
+# Rollback Strategy 1: Update SDK initialization
+def rollback_via_sdk():
+ """Rollback to previous version by updating SDK configuration"""
+
+ # Previous configuration (problematic)
+ # composio = Composio(
+ # api_key="YOUR_API_KEY",
+ # toolkit_versions={
+ # "github": "20250116_00" # New version causing issues
+ # }
+ # )
+
+ # Rollback to stable version
+ composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={
+ "github": "20250110_00" # Previous stable version
+ }
+ )
+
+ print("Rolled back GitHub toolkit to version 20250110_00")
+ return composio
+
+# Rollback Strategy 2: Update environment variables
+def rollback_via_env():
+ """Rollback by updating environment variables"""
+
+ # Set the stable version
+ os.environ["COMPOSIO_TOOLKIT_VERSION_GITHUB"] = "20250110_00"
+
+ # Initialize SDK (will use environment variable)
+ composio = Composio(api_key="YOUR_API_KEY")
+
+ print("Rolled back via environment variable")
+ return composio
+
+# Rollback Strategy 3: Emergency skip version check
+def emergency_rollback():
+ """Emergency rollback when version system itself has issues"""
+
+ composio = Composio(api_key="YOUR_API_KEY")
+
+ # Skip version check temporarily (use with caution)
+ result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "title": "Critical fix",
+ "body": "Emergency deployment"
+ },
+ "dangerously_skip_version_check": True
+ }
+ )
+
+ print("⚠️ Executed with version check skipped - fix version config ASAP")
+ return result
\ 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..18da3471d
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/sdk-initialization.py
@@ -0,0 +1,31 @@
+from composio import Composio
+
+# Initialize SDK with specific toolkit versions
+composio = Composio(
+ api_key="YOUR_API_KEY",
+ toolkit_versions={
+ "github": "20250116_00",
+ "slack": "20250115_01",
+ "gmail": "latest" # Use latest version for development
+ }
+)
+
+# Fetch tools - they will use the specified versions
+tools = composio.tools.get(
+ user_id="user-123",
+ toolkits=["github", "slack"]
+)
+
+# Execute a tool - inherits version from SDK initialization
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "user-123",
+ "arguments": {
+ "repo": "my-repo",
+ "owner": "my-org",
+ "title": "Bug report",
+ "body": "Issue description"
+ }
+ }
+)
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/python/test-new-version.py b/fern/snippets/tool-calling/versioning/python/test-new-version.py
new file mode 100644
index 000000000..64413294d
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/python/test-new-version.py
@@ -0,0 +1,84 @@
+from composio import Composio
+import pytest
+
+def test_new_github_version():
+ """Test a new GitHub toolkit version before production deployment"""
+
+ # Initialize with new version to test
+ test_composio = Composio(
+ api_key="YOUR_TEST_KEY",
+ toolkit_versions={"github": "20250116_00"}
+ )
+
+ # Test basic tool execution
+ result = test_composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ {
+ "user_id": "test-user",
+ "arguments": {
+ "repo": "test-repo",
+ "owner": "test-org",
+ "title": "Test issue",
+ "body": "Testing new version"
+ }
+ }
+ )
+
+ assert result["successful"] == True
+ assert "issue_number" in result["data"]
+
+ # Test tool fetching
+ tools = test_composio.tools.get(
+ user_id="test-user",
+ toolkits=["github"]
+ )
+
+ assert len(tools) > 0
+ assert all(tool.toolkit == "github" for tool in tools)
+
+ print("βœ“ New version tests passed")
+ return True
+
+def test_version_compatibility():
+ """Ensure new version maintains backward compatibility"""
+
+ old_version = "20250110_00"
+ new_version = "20250116_00"
+
+ # Initialize with old version
+ old_composio = Composio(
+ api_key="YOUR_TEST_KEY",
+ toolkit_versions={"github": old_version}
+ )
+
+ # Initialize with new version
+ new_composio = Composio(
+ api_key="YOUR_TEST_KEY",
+ toolkit_versions={"github": new_version}
+ )
+
+ # Get tools from both versions
+ old_tools = old_composio.tools.get(
+ user_id="test-user",
+ toolkits=["github"]
+ )
+
+ new_tools = new_composio.tools.get(
+ user_id="test-user",
+ toolkits=["github"]
+ )
+
+ # Check that essential tools still exist
+ old_tool_slugs = {tool.slug for tool in old_tools}
+ new_tool_slugs = {tool.slug for tool in new_tools}
+
+ essential_tools = [
+ "GITHUB_CREATE_ISSUE",
+ "GITHUB_CREATE_PULL_REQUEST",
+ "GITHUB_LIST_ISSUES"
+ ]
+
+ for tool in essential_tools:
+ assert tool in new_tool_slugs, f"Essential tool {tool} missing in new version"
+
+ print("βœ“ Backward compatibility verified")
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/breaking-changes.ts b/fern/snippets/tool-calling/versioning/typescript/breaking-changes.ts
new file mode 100644
index 000000000..39139d895
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/breaking-changes.ts
@@ -0,0 +1,59 @@
+import { Composio } from "@composio/core";
+
+const composio = new Composio({ apiKey: "YOUR_API_KEY" });
+
+// ❌ This will fail without version specification (after October 22, 2025)
+try {
+ const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Bug report",
+ body: "Issue description"
+ }
+ });
+} catch (error) {
+ console.error("Error:", error);
+ console.log("Manual execution requires toolkit version");
+}
+
+// βœ… Solution 1: Specify version in execution
+const result1 = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Bug report",
+ body: "Issue description"
+ },
+ toolkitVersion: "20250116_00"
+});
+
+// βœ… Solution 2: Configure version at SDK level
+const composioWithVersion = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: { github: "20250116_00" }
+});
+
+const result2 = await composioWithVersion.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Bug report",
+ body: "Issue description"
+ }
+});
+
+// ⚠️ Emergency escape hatch (not recommended for production)
+const result3 = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Bug report",
+ body: "Issue description"
+ },
+ dangerouslySkipVersionCheck: true
+});
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/environment-variables.ts b/fern/snippets/tool-calling/versioning/typescript/environment-variables.ts
new file mode 100644
index 000000000..4bd682004
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/environment-variables.ts
@@ -0,0 +1,23 @@
+import { Composio } from "@composio/core";
+
+// Set environment variables before running your application
+// export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
+// export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
+
+// Or set a global version for all toolkits
+// export COMPOSIO_TOOLKIT_VERSION="20250116_00"
+
+// SDK automatically reads environment variables
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY"
+});
+
+// Tools will use versions from environment variables
+const tools = await composio.tools.get("user-123", {
+ toolkits: ["github", "slack"]
+});
+
+// Check which versions are being used
+tools.forEach(tool => {
+ console.log(`Tool: ${tool.slug}, Version: ${tool.toolkitVersion}`);
+});
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/list-versions.ts b/fern/snippets/tool-calling/versioning/typescript/list-versions.ts
new file mode 100644
index 000000000..560a0e08e
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/list-versions.ts
@@ -0,0 +1,30 @@
+import { Composio } from "@composio/core";
+
+const composio = new Composio({ apiKey: "YOUR_API_KEY" });
+
+// Get all available versions for a toolkit
+const versions = await composio.tools.getToolkitVersions("github");
+
+// Display version information
+versions.forEach(version => {
+ console.log(`Version: ${version.version}`);
+ console.log(`Released: ${version.createdAt}`);
+ console.log(`Status: ${version.status}`);
+ console.log("-".repeat(40));
+});
+
+// Find the latest stable version
+const stableVersions = versions.filter(v => v.status === 'stable');
+if (stableVersions.length > 0) {
+ const latestStable = stableVersions[0];
+ console.log(`Latest stable version: ${latestStable.version}`);
+}
+
+// Find versions released in the last 7 days
+const recentVersions = versions.filter(version => {
+ const releaseDate = new Date(version.createdAt);
+ const daysAgo = Math.floor((Date.now() - releaseDate.getTime()) / (1000 * 60 * 60 * 24));
+ return daysAgo <= 7;
+});
+
+console.log(`Versions released in last 7 days: ${recentVersions.length}`);
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/multi-environment.ts b/fern/snippets/tool-calling/versioning/typescript/multi-environment.ts
new file mode 100644
index 000000000..b63ae5249
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/multi-environment.ts
@@ -0,0 +1,32 @@
+import { Composio } from "@composio/core";
+
+// Get current environment from environment variable
+const env = process.env.ENVIRONMENT || "development";
+
+// Define version configurations for each environment
+const versionConfigs = {
+ development: {
+ github: "latest",
+ slack: "latest",
+ gmail: "latest"
+ },
+ staging: {
+ github: "20250116_00", // Test new GitHub version
+ slack: "20250110_00", // Keep stable Slack version
+ gmail: "20250110_00"
+ },
+ production: {
+ github: "20250110_00", // Stable, tested version
+ slack: "20250110_00", // Stable, tested version
+ gmail: "20250109_00" // Stable, tested version
+ }
+};
+
+// Initialize Composio with environment-specific versions
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY!,
+ toolkitVersions: versionConfigs[env as keyof typeof versionConfigs]
+});
+
+console.log(`Environment: ${env}`);
+console.log(`Toolkit versions:`, versionConfigs[env as keyof typeof versionConfigs]);
\ 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..5efcb828e
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts
@@ -0,0 +1,29 @@
+import { Composio } from "@composio/core";
+
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: {
+ github: "20250110_00" // Default version
+ }
+});
+
+// Override version for a single execution
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Bug report",
+ body: "Description here"
+ },
+ toolkitVersion: "20250115_00" // Override to different version
+});
+
+// This execution uses the SDK default version
+const result2 = await composio.tools.execute({
+ toolSlug: "GITHUB_LIST_ISSUES",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo"
+ }
+});
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/rollback.ts b/fern/snippets/tool-calling/versioning/typescript/rollback.ts
new file mode 100644
index 000000000..d2eb90c05
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/rollback.ts
@@ -0,0 +1,59 @@
+import { Composio } from "@composio/core";
+
+// Rollback Strategy 1: Update SDK initialization
+async function rollbackViaSdk(): Promise<Composio> {
+ // Previous configuration (problematic)
+ // const composio = new Composio({
+ // apiKey: "YOUR_API_KEY",
+ // toolkitVersions: {
+ // github: "20250116_00" // New version causing issues
+ // }
+ // });
+
+ // Rollback to stable version
+ const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: {
+ github: "20250110_00" // Previous stable version
+ }
+ });
+
+ console.log("Rolled back GitHub toolkit to version 20250110_00");
+ return composio;
+}
+
+// Rollback Strategy 2: Update environment variables
+async function rollbackViaEnv(): Promise<Composio> {
+ // Set the stable version
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = "20250110_00";
+
+ // Initialize SDK (will use environment variable)
+ const composio = new Composio({
+ apiKey: "YOUR_API_KEY"
+ });
+
+ console.log("Rolled back via environment variable");
+ return composio;
+}
+
+// Rollback Strategy 3: Emergency skip version check
+async function emergencyRollback(): Promise<any> {
+ const composio = new Composio({
+ apiKey: "YOUR_API_KEY"
+ });
+
+ // Skip version check temporarily (use with caution)
+ const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ title: "Critical fix",
+ body: "Emergency deployment"
+ },
+ dangerouslySkipVersionCheck: true
+ });
+
+ console.log("⚠️ Executed with version check skipped - fix version config ASAP");
+ return result;
+}
\ 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..e9466848b
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts
@@ -0,0 +1,28 @@
+import { Composio } from "@composio/core";
+
+// Initialize SDK with specific toolkit versions
+const composio = new Composio({
+ apiKey: "YOUR_API_KEY",
+ toolkitVersions: {
+ github: "20250116_00",
+ slack: "20250115_01",
+ gmail: "latest" // Use latest version for development
+ }
+});
+
+// Fetch tools - they will use the specified versions
+const tools = await composio.tools.get("user-123", {
+ toolkits: ["github", "slack"]
+});
+
+// Execute a tool - inherits version from SDK initialization
+const result = await composio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "user-123",
+ arguments: {
+ repo: "my-repo",
+ owner: "my-org",
+ title: "Bug report",
+ body: "Issue description"
+ }
+});
\ No newline at end of file
diff --git a/fern/snippets/tool-calling/versioning/typescript/test-new-version.ts b/fern/snippets/tool-calling/versioning/typescript/test-new-version.ts
new file mode 100644
index 000000000..1862b7f45
--- /dev/null
+++ b/fern/snippets/tool-calling/versioning/typescript/test-new-version.ts
@@ -0,0 +1,89 @@
+import { Composio } from "@composio/core";
+
+async function testNewGithubVersion(): Promise<boolean> {
+ // Initialize with new version to test
+ const testComposio = new Composio({
+ apiKey: "YOUR_TEST_KEY",
+ toolkitVersions: { github: "20250116_00" }
+ });
+
+ // Test basic tool execution
+ const result = await testComposio.tools.execute({
+ toolSlug: "GITHUB_CREATE_ISSUE",
+ userId: "test-user",
+ arguments: {
+ repo: "test-repo",
+ owner: "test-org",
+ title: "Test issue",
+ body: "Testing new version"
+ }
+ });
+
+ if (!result.successful) {
+ throw new Error("Tool execution failed");
+ }
+
+ if (!result.data.issue_number) {
+ throw new Error("Missing expected data in response");
+ }
+
+ // Test tool fetching
+ const tools = await testComposio.tools.get("test-user", {
+ toolkits: ["github"]
+ });
+
+ if (tools.length === 0) {
+ throw new Error("No tools returned");
+ }
+
+ if (!tools.every(tool => tool.toolkit === "github")) {
+ throw new Error("Unexpected toolkit in results");
+ }
+
+ console.log("βœ“ New version tests passed");
+ return true;
+}
+
+async function testVersionCompatibility(): Promise<void> {
+ const oldVersion = "20250110_00";
+ const newVersion = "20250116_00";
+
+ // Initialize with old version
+ const oldComposio = new Composio({
+ apiKey: "YOUR_TEST_KEY",
+ toolkitVersions: { github: oldVersion }
+ });
+
+ // Initialize with new version
+ const newComposio = new Composio({
+ apiKey: "YOUR_TEST_KEY",
+ toolkitVersions: { github: newVersion }
+ });
+
+ // Get tools from both versions
+ const oldTools = await oldComposio.tools.get("test-user", {
+ toolkits: ["github"]
+ });
+
+ const newTools = await newComposio.tools.get("test-user", {
+ toolkits: ["github"]
+ });
+
+ // Check that essential tools still exist
+ const oldToolSlugs = new Set(oldTools.map(tool => tool.slug));
+ const newToolSlugs = new Set(newTools.map(tool => tool.slug));
+
+ const essentialTools = [
+ "GITHUB_CREATE_ISSUE",
+ "GITHUB_CREATE_PULL_REQUEST",
+ "GITHUB_LIST_ISSUES"
+ ];
+
+ for (const tool of essentialTools) {
+ if (!newToolSlugs.has(tool)) {
+ throw new Error(`Essential tool ${tool} missing in new version`);
+ }
+ }
+
+ console.log("βœ“ Backward compatibility verified");
+}
\ No newline at end of file