Toolkit Versioning
If you're building an agent, we recommend using sessions instead. Sessions handle toolkit versions automatically so you don't have to manage them yourself.
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.
To view available versions, go to Dashboard > All Toolkits > select a toolkit. The version dropdown shows the latest and all available versions:
You can also find the latest version for each toolkit on the Toolkits page in the docs. Select a toolkit to see its current version and available tools.
Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.
Default version behavior
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. To get all available tools including ones added in newer versions, explicitly set toolkit_versions to "latest" or a specific version.
This applies to both the SDK and direct REST API calls:
# Without version — returns only tools from the base version
curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive' \
-H 'x-api-key: YOUR_API_KEY'
# With version=latest — returns all tools including newer ones
curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
-H 'x-api-key: YOUR_API_KEY'Configuration methods
Configure toolkit versions using one of three methods:
SDK initialization
from composio import Composio
# Pin specific versions for each toolkit
composio = Composio(
api_key="YOUR_API_KEY",
toolkit_versions={
"github": "20251027_00",
"slack": "20251027_00",
"gmail": "20251027_00"
}
)import { Composio } from "@composio/core";
// Pin specific versions for each toolkit
const composio = new Composio({
apiKey: "YOUR_API_KEY",
toolkitVersions: {
github: "20251027_00",
slack: "20251027_00",
gmail: "20251027_00"
}
});Environment variables
# Set versions for specific toolkits
export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"
export COMPOSIO_TOOLKIT_VERSION_SLACK="20251027_00"
export COMPOSIO_TOOLKIT_VERSION_GMAIL="20251027_00"Per-execution override
from composio import Composio
composio = Composio(api_key="YOUR_API_KEY")
# Specify version directly in execute call
result = composio.tools.execute(
"GITHUB_LIST_STARGAZERS",
arguments={
"owner": "ComposioHQ",
"repo": "composio"
},
user_id="user-k7334",
version="20251027_00" # Override version for this execution
)
print(result)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("GITHUB_LIST_STARGAZERS", {
userId: "user-k7334",
arguments: {
owner: "ComposioHQ",
repo: "composio"
},
version: "20251027_00" // Override version for this execution
});
console.log(result);Version format
Versions follow the format YYYYMMDD_NN:
YYYYMMDD: Release dateNN: Sequential release number
# Production — pin to a specific version
toolkit_versions = {"github": "20251027_00"}
# Development — always use the newest tools
toolkit_versions = {"github": "latest"}Never use latest in production. It can introduce breaking changes. Pin to a specific version instead.
Version resolution order
- Per-execution version (highest priority)
- SDK initialization version
- Environment variable (toolkit-specific)
Managing versions
Check available versions using:
# Get toolkit information including available versions
toolkit = composio.toolkits.get(slug="github")
# Extract and print version information
print(f"Toolkit: {toolkit.name}")
print(f"Current Version: {toolkit.meta.version}")
print(f"Available Versions: {toolkit.meta.available_versions}")// Get toolkit information including available versions
const toolkit = await composio.toolkits.get("github");
// Extract and print version information
console.log("Toolkit:", toolkit.name);
console.log("Available Versions:", toolkit.meta.availableVersions);
console.log("Latest Version:", toolkit.meta.availableVersions?.[0]);