November 10, 2025 | Composio Docs

Toolkit Version Support for Triggers

Summary

Added toolkit version support to trigger operations (create and getType) in both Python and TypeScript SDKs. This allows users to explicitly specify which toolkit version to use when creating trigger instances and retrieving trigger type information, ensuring consistent behavior across different toolkit versions.

Trigger operations now respect the global toolkitVersions configuration set during Composio initialization, providing better control over which trigger versions are used in your applications.

Key Changes

TypeScript SDK (`ts/packages/core/`)

Added toolkit_versions parameter to triggers.create() method
- Passes the global toolkit versions configuration when creating trigger instances
- Defaults to 'latest' when no version is specified
Modified triggers.getType() to respect global toolkit versions
- Now accepts toolkit version configuration to fetch trigger types for specific versions
- Improved error messages to include version-related fixes
Updated trigger type documentation with comprehensive examples
Added behavior documentation explaining version usage patterns

Python SDK (`python/composio/core/models/`)

Added toolkit_versions parameter to triggers.create() method
- Uses global toolkit version configuration when creating trigger instances
- Converts None to omit for API compatibility
Modified triggers.get_type() to respect toolkit versions
- Implemented custom method replacing direct client binding
- Passes toolkit version configuration to API calls
Added comprehensive docstrings explaining version behavior

Behavior

Creating Triggers with Toolkit Versions:

1 // TypeScript - Configure versions at initialization
2 const composio = new Composio({
3   apiKey: 'your-api-key',
4   toolkitVersions: {
5     gmail: '12082025_00',
6     github: '10082025_01'
7   }
8 });
9 
10 // Create trigger - uses version '12082025_00' for Gmail
11 const trigger = await composio.triggers.create('user@example.com', 'GMAIL_NEW_MESSAGE', {
12   connectedAccountId: 'ca_abc123',
13   triggerConfig: {
14     labelIds: 'INBOX',
15     userId: 'me',
16     interval: 60,
17   },
18 });

1 # Python - Configure versions at initialization
2 composio = Composio(
3     api_key="your-api-key",
4     toolkit_versions={"gmail": "12082025_00", "github": "10082025_01"}
5 )
6 
7 # Create trigger - uses version '12082025_00' for Gmail
8 trigger = composio.triggers.create(
9     slug="GMAIL_NEW_MESSAGE",
10     user_id="user@example.com",
11     trigger_config={"labelIds": "INBOX", "userId": "me", "interval": 60}
12 )

Retrieving Trigger Types with Specific Versions:

1 // TypeScript
2 const composio = new Composio({
3   apiKey: 'your-api-key',
4   toolkitVersions: { github: '10082025_01' }
5 });
6 
7 // Get trigger type for specific version
8 const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
9 // Returns trigger type for version '10082025_01'

1 # Python
2 composio = Composio(
3     api_key="your-api-key",
4     toolkit_versions={"github": "10082025_01"}
5 )
6 
7 # Get trigger type for specific version
8 trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
9 # Returns trigger type for version '10082025_01'

Benefits

Version Control: Explicitly specify which toolkit version to use for triggers
Consistency: Ensure trigger behavior remains consistent across toolkit updates
Testing: Test trigger integrations with specific versions before updating
Debugging: Easier to debug issues by pinning to specific toolkit versions
Production Safety: Avoid unexpected changes from automatic version updates

Migration Guide

This is a non-breaking change. Existing code will continue to work with default behavior:

Before (still works):

1 // Uses 'latest' version by default
2 const trigger = await composio.triggers.create('user', 'GITHUB_COMMIT_EVENT', {...});

After (recommended for production):

1 // Explicitly configure versions for better control
2 const composio = new Composio({
3   apiKey: 'your-api-key',
4   toolkitVersions: { github: '10082025_01' }
5 });
6 
7 const trigger = await composio.triggers.create('user', 'GITHUB_COMMIT_EVENT', {...});

For more details on toolkit versioning, see the Toolkit Versioning documentation.

1	// TypeScript - Configure versions at initialization
2	const composio = new Composio({
3	apiKey: 'your-api-key',
4	toolkitVersions: {
5	gmail: '12082025_00',
6	github: '10082025_01'
7	}
8	});
9
10	// Create trigger - uses version '12082025_00' for Gmail
11	const trigger = await composio.triggers.create('user@example.com', 'GMAIL_NEW_MESSAGE', {
12	connectedAccountId: 'ca_abc123',
13	triggerConfig: {
14	labelIds: 'INBOX',
15	userId: 'me',
16	interval: 60,
17	},
18	});

1	# Python - Configure versions at initialization
2	composio = Composio(
3	api_key="your-api-key",
4	toolkit_versions={"gmail": "12082025_00", "github": "10082025_01"}
5	)
6
7	# Create trigger - uses version '12082025_00' for Gmail
8	trigger = composio.triggers.create(
9	slug="GMAIL_NEW_MESSAGE",
10	user_id="user@example.com",
11	trigger_config={"labelIds": "INBOX", "userId": "me", "interval": 60}
12	)

1	// TypeScript
2	const composio = new Composio({
3	apiKey: 'your-api-key',
4	toolkitVersions: { github: '10082025_01' }
5	});
6
7	// Get trigger type for specific version
8	const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
9	// Returns trigger type for version '10082025_01'

1	# Python
2	composio = Composio(
3	api_key="your-api-key",
4	toolkit_versions={"github": "10082025_01"}
5	)
6
7	# Get trigger type for specific version
8	trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
9	# Returns trigger type for version '10082025_01'

1	// Uses 'latest' version by default
2	const trigger = await composio.triggers.create('user', 'GITHUB_COMMIT_EVENT', {...});

1	// Explicitly configure versions for better control
2	const composio = new Composio({
3	apiKey: 'your-api-key',
4	toolkitVersions: { github: '10082025_01' }
5	});
6
7	const trigger = await composio.triggers.create('user', 'GITHUB_COMMIT_EVENT', {...});