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.
Per-execution override
Passversion directly to composio.tools.execute() to pin one call. The per-call value takes precedence over SDK initialization and environment variables, and leaves the defaults for other calls unchanged.
These examples use 20251027_00. Replace it with an available version you have tested for your toolkit.
- Python
- TypeScript
- API
Find available versions
To view recent versions, go to Dashboard > All Toolkits > select a toolkit. Use the version dropdown to choose a version:
The toolkit metadata’s
available_versions list (availableVersions in TypeScript) contains at most the 50 newest versions. A version dropping out of that list does not retire it or stop pinned execution. Use the deprecation and sunset policy, response warnings, and execution errors to determine when you need to upgrade. Keep your tested version in your own configuration rather than replacing it just because it is absent from the discovery list.Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution — and
"latest" is not accepted there on its own. To run the newest version with tools.execute(), pass dangerously_skip_version_check=True (TypeScript: dangerouslySkipVersionCheck: true) on the call; otherwise pin a dated version. "latest" works without the flag everywhere else (fetching tools, sessions).Default version behavior
For example, a v3 tools-list request withouttoolkit_versions returns the base version:
- Python
- TypeScript
- API
Configuration methods
To use the same version across calls, set a default at SDK initialization or through environment variables. A per-execution override takes precedence over either default.SDK initialization
- Python
- TypeScript
Environment variables
Version format
Versions follow the formatYYYYMMDD_NN:
YYYYMMDD: Release dateNN: Sequential release number
- Python
- TypeScript
Choosing between latest and a pinned version
The right choice depends on how your application consumes tool outputs:
- Use
latestwhen tool outputs are consumed by an LLM or AI agent. Agents interpret responses dynamically and adapt to changes in output structure. Usinglatestensures your agent always has access to the newest tools and improvements without manual intervention. For manual execution (tools.execute()),latestrequires the explicit opt-indangerously_skip_version_check=True/dangerouslySkipVersionCheck: trueon 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.
As a rule of thumb: if an LLM reads the output, use
latest. If your code parses the output, pin the version.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
- Per-execution version (highest priority)
- SDK initialization version
- Environment variable (toolkit-specific)
Managing versions
Check available versions using:- Python
- TypeScript
- API
Retrieve toolkit changelogs
Callcomposio.toolkits.changelog() in Python or await composio.toolkits.changelog() in TypeScript to retrieve the last 10 versions for each toolkit. The response’s items contain each toolkit’s slug and version entries, which you can review before changing a pinned version.
Deprecation and sunset
Composio-managed toolkit versions are deprecated 12 months after they’re published and retired 3 months after that. The newest version of a toolkit is never deprecated, so pinning a current version and upgrading on your own schedule keeps you clear of both dates. When a request resolves to a deprecated version, the API adds aComposio-Deprecated-Toolkits response header alongside the normal response:
version, plus optional deprecated and sunset dates (Unix seconds, prefixed with @) and a reason. Versions deprecated by hand carry only version.
Single-toolkit routes carry the header: toolkit get, tool get, tool execute, text-to-request, trigger type get, trigger upsert and setup, and trigger authorization entities. Listing endpoints never do.
SDK warning
Both SDKs read the header and warn once per process for each deprecated toolkit version. The call still succeeds.- Python
- TypeScript
ComposioDeprecationWarning (a UserWarning subclass), so standard warning filters apply:reason or sunset, the warning omits those clauses too.
Moving off a deprecated version
Pick a newer version from the dashboard ortoolkits.get(), then pin it the same way you pin any version: at SDK initialization, through an environment variable, or per execute call. The warning stops as soon as requests resolve to a version that isn’t deprecated.
After the sunset date, requests for the retired version fail with HTTP 410 Gone until you pin a supported version.