> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Toolkit versioning migration

> Migrate to the new toolkit versioning system

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)

> [tab] Python
>
> ```python theme={null}
> # Raises ToolVersionRequiredError
> result = composio.tools.execute(
>     "GITHUB_CREATE_ISSUE",
>     arguments={"owner": "composio", "repo": "composio", "title": "Bug report"},
>     user_id="user-123",
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> // Throws ComposioToolVersionRequiredError
> const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
>     userId: "user-123",
>     arguments: { owner: "composio", repo: "composio", title: "Bug report" }
> });
> ```

### After (required)

Choose one of three migration strategies:

#### Option 1: Configure version at SDK level

> [tab] Python
>
> ```python theme={null}
> 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"
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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"
>     }
> });
> ```

#### Option 2: Pass version with each execution

> [tab] Python
>
> ```python theme={null}
> # 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)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> // 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);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_LIST_STARGAZERS \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user-k7334",
>     "arguments": {"owner": "ComposioHQ", "repo": "composio"},
>     "version": "20251027_00"
>   }'
> ```

#### Option 3: Use environment variables

```bash theme={null}
export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"
```

## 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):

> [tab] Python
>
> ```python theme={null}
> result = composio.tools.execute(
>     "GITHUB_CREATE_ISSUE",
>     arguments={"owner": "composio", "repo": "composio", "title": "Bug report"},
>     user_id="user-123",
>     dangerously_skip_version_check=True,
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
>     userId: "user-123",
>     arguments: { owner: "composio", repo: "composio", title: "Bug report" },
>     dangerouslySkipVersionCheck: true
> });
> ```

> [!WARNING]
>
> The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never use in production.

## Next

> [card] [Migrate to sessions](https://composio-preview.mintlify.site/docs/migration-guide/direct-to-sessions.md)
>
> Move from older tool execution patterns to sessions
