Toolkit Versioning

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.

Default version behavior

For example, a v3 tools-list request without toolkit_versions returns the base version:

# Without toolkit_versions: returns tools from the base version
curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive' \
  -H 'x-api-key: YOUR_API_KEY'

# With toolkit_versions=latest: returns tools from the latest version
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"
    }
)

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)

Version format

Versions follow the format YYYYMMDD_NN:

• YYYYMMDD: Release date
• NN: Sequential release number

# Pin to a specific version
toolkit_versions = {"github": "20251027_00"}

# Always use the newest tools (manual execution additionally requires
# dangerously_skip_version_check=True on the execute call)
toolkit_versions = {"github": "latest"}

Choosing between latest and a pinned version

The right choice depends on how your application consumes tool outputs:

• Use latest when tool outputs are consumed by an LLM or AI agent. Agents interpret responses dynamically and adapt to changes in output structure. Using latest ensures your agent always has access to the newest tools and improvements without manual intervention. For manual execution (tools.execute()), latest requires the explicit opt-in dangerously_skip_version_check=True / dangerouslySkipVersionCheck: true on the call — the flag's name is the reminder that output schemas can change between releases.

• Pin a specific version when tool outputs are consumed programmatically — for example, if your code destructures specific fields from a response, maps outputs to a database schema, or feeds results into a typed pipeline. Schema changes in a new version could silently break these integrations.

Most agentic applications — including all session-based workflows — use latest by default and benefit from always having the most up-to-date tools. If you're building structured data pipelines or integrations with fixed response parsing, pin to a tested version and upgrade on your own schedule.

Version resolution order

1. Per-execution version (highest priority)
2. SDK initialization version
3. 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}")

Next