Changelog

Version Information

TypeScript/JavaScript

• Package: @composio/core and all provider packages
• Version: 0.6.3+
• PR: #2570

The important flag auto-apply logic has been updated to respect the limit parameter. When you provide a limit, the SDK no longer automatically applies important: true, ensuring you get the exact number of tools you requested.

What Changed

Previously, when querying tools by toolkit with both toolkits and limit parameters, the SDK would auto-apply important: true. This could result in returning fewer tools than the requested limit if the toolkit had limited important tools.

Before:

// Could return < 50 tools if only 10 important tools exist
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 50,
});
// Result: Only 10 tools (important ones only)

After:

// Returns exactly 50 tools (or all available if < 50)
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 50,
});
// Result: 50 tools (including non-important)

Auto-Apply Logic

The important flag is now auto-applied only when ALL of these conditions are met:

• toolkits is provided
• tools is NOT provided
• tags is NOT provided
• search is NOT provided
• limit is NOT provided ← NEW
• important is NOT explicitly set to false

Examples

Auto-Applies Important (No Limit)

const tools = await composio.tools.get('default', {
  toolkits: ['github'],
});
// Returns: ~10-20 important tools

Does NOT Auto-Apply (Limit Provided)

const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 50,
});
// Returns: Exactly 50 tools (or all available)

Explicit Important Overrides

const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 50,
  important: true,
});
// Returns: Up to 50 important tools

Prevents Auto-Apply (Tags Provided)

const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  tags: ['important'],
});
// Returns: GitHub tools with 'important' tag (no auto-apply)

Prevents Auto-Apply (Search Provided)

const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  search: 'repository',
});
// Returns: GitHub tools matching search (no auto-apply)

Why This Matters

When you provide a limit, you're explicitly requesting a specific number of tools. Auto-applying the important filter could prevent you from getting the requested number of tools. This change respects user intent and makes the SDK behavior more predictable.

Use cases:

1. Pagination: Get exactly N tools per page
2. Performance: Limit tool count for faster responses
3. UI constraints: Display a specific number of tools in your interface

Backward Compatibility

This change is backward compatible with one caveat:

• No code changes needed for most users
• If you were relying on automatic important filtering with limit, you now need to explicitly pass important: true

Migration (if needed):

// Before (relied on auto-apply even with limit)
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 20,
});

// After (explicit important flag)
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 20,
  important: true, // Explicitly set if you want important tools
});

Documentation

Full documentation with more examples is available in the Tools API Reference.

We've expanded our typed response support to include three major toolkits—GitHub, Mailchimp, and Trello—while also adding more typed actions across previously updated toolkits. All outputs now return strongly typed objects with clear field documentation instead of generic response_data blobs, enabling better IDE support and more reliable agent interactions.

Why This Matters

• Enhanced type safety: GitHub, Mailchimp, and Trello now have fully typed responses
• Expanded action coverage: More actions in existing toolkits now return typed data
• Improved developer experience: Better autocomplete and field validation across all toolkits
• Agent-friendly schemas: Cleaner output shapes reduce parsing errors and improve AI tool usage

Coming Soon: 40+ More Toolkits

We're planning to expand typed response coverage to 40+ additional toolkits in upcoming releases.

Tool schemas are now cleaner for optional fields by removing redundant anyOf: [{type}, {type: "null"}] constructs.

Background: How JSON Schema Handles Optional Fields

In JSON Schema, there are two distinct concepts:

Previously, our schemas used anyOf with null type for all optional fields—even when the field wasn't in required. This was redundant: if a field can be omitted, explicitly marking it as "accepts null" adds no value.

What Changed

For fields that are not in the required array, the schema processing now:

• Removes the redundant {type: "null"} from anyOf arrays
• Removes default: null since it's implied by being optional
• Flattens single-type anyOf to direct type declarations

Before vs After

For example, the page_token field in GOOGLECALENDAR_LIST_CALENDARS (which is optional/not required):

Previous (verbose):

{
  "page_token": {
    "anyOf": [
      { "type": "string" },
      { "type": "null" }
    ],
    "default": null,
    "description": "Token for the page of results to return...",
    "title": "Page Token"
  }
}

Now (simplified):

{
  "page_token": {
    "type": "string",
    "description": "Token for the page of results to return...",
    "title": "Page Token"
  }
}

What's Preserved

• Required nullable fields: Fields in the required array that accept null still use anyOf with null type
• Union types: Fields accepting multiple value types (e.g., string | number) retain their full anyOf array

Why This Matters

• Fewer tokens: Simpler schemas reduce token usage when tools are passed to LLMs
• Better compatibility: Some code generators and validators handle direct types better than anyOf constructs
• Clearer semantics: Non-required fields don't need explicit null type—being optional already implies they can be omitted

Version Information

TypeScript/JavaScript

• Package: @composio/core and all provider packages
• Version: 0.6.0+

Python

• Package: composio and all provider packages
• Version: 0.11.0+

This major release focuses on Cloudflare Workers compatibility, platform-specific optimizations, and critical bug fixes. It includes breaking changes in both TypeScript and Python SDKs.

Breaking Changes

1. Webhook Verification Breaking Changes

TypeScript PR: #2436 | Python PR: #2361

The webhook verification API has breaking changes in both SDKs to support multiple webhook versions (v1, v2, v3) and edge runtime compatibility.

TypeScript: Now Async + Signature Changed

The verifyWebhook() method has two breaking changes: it's now async AND requires additional parameters.

Before:

import { Composio } from '@composio/core';

const composio = new Composio();

// Old signature - synchronous, fewer parameters
const payload = composio.triggers.verifyWebhook({
  payload: req.body.toString(),
  signature: req.headers['x-composio-signature'] as string,
  secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
});
// Returns: TriggerEvent

After:

import { Composio } from '@composio/core';

const composio = new Composio();

// New signature - async, requires id and timestamp
const result = await composio.triggers.verifyWebhook({
  id: req.headers['webhook-id'] as string, // NEW: required
  payload: req.body.toString(),
  secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
  signature: req.headers['webhook-signature'] as string, // header name changed
  timestamp: req.headers['webhook-timestamp'] as string, // NEW: required
  tolerance: 300, // optional, default 300 seconds
});
// Returns: VerifyWebhookResult with version info

Key Changes:

• ⚠️ Now async - Must use await
• ⚠️ New required parameter: id (from webhook-id header)
• ⚠️ New required parameter: timestamp (from webhook-timestamp header)
• ⚠️ Header name changed: x-composio-signature → webhook-signature
• ⚠️ Return type changed: TriggerEvent → VerifyWebhookResult

Why?

• Cloudflare Workers compatibility - uses Web Crypto API instead of node:crypto
• Supports v1, v2, and v3 webhook formats with improved signature verification

Python: Signature Changed (v1/v2/v3 Support)

The method signature changed to support new webhook versions and requires additional headers.

Before:

from composio import Composio

composio = Composio()

# Old signature - fewer parameters
event = composio.triggers.verify_webhook(
    payload=request.get_data(as_text=True),
    signature=request.headers.get('x-composio-signature'),
    secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
)
# Returns: TriggerEvent

After:

from composio import Composio

composio = Composio()

# New signature - requires id and timestamp headers
result = composio.triggers.verify_webhook(
    id=request.headers.get('webhook-id'),           # NEW: required
    payload=request.get_data(as_text=True),
    secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
    signature=request.headers.get('webhook-signature'),  # header name changed
    timestamp=request.headers.get('webhook-timestamp'),  # NEW: required
    tolerance=300,  # optional
)
# Returns: VerifyWebhookResult with version info

Key Changes:

• ✅ Still synchronous (no await needed)
• ⚠️ New required parameter: id (webhook-id header)
• ⚠️ New required parameter: timestamp (webhook-timestamp header)
• ⚠️ Header name changed: x-composio-signature → webhook-signature
• ⚠️ Return type changed: TriggerEvent → VerifyWebhookResult
• ⚠️ All parameters now keyword-only (must use param=value)

Why? Supports v1, v2, and v3 webhook formats with improved signature verification.

2. Mastra v1 Provider Update

PR: #2433

The @composio/mastra provider has been updated to support Mastra v1, which has breaking API changes from v0.x.

Before (Mastra v0.x)

import { MastraProvider } from '@composio/mastra';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  /* v0 config */
});
const provider = new MastraProvider();

// v0 API usage
const tools = await provider.wrapTools(composioTools);

After (Mastra v1)

import { MastraProvider } from '@composio/mastra';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  /* v1 config */
});
const provider = new MastraProvider({ mastra });

// v1 API - different tool format
const tools = await provider.wrapTools(composioTools);

Changes Required

1. Update Mastra dependency: npm install @mastra/core@latest
2. Update provider initialization: Pass Mastra instance to provider
3. Update tool handling: Mastra v1 uses different tool schema format
4. Check Zod version: Mastra v1 supports both Zod v3 and v4
5. Check Node.js version: Mastra v1 requires Node.js v22.13.0 or higher

Major Features

3. Platform-Specific File Tool Modifier

PR: #2437

Separate implementations for Node.js and Cloudflare Workers to optimize file handling for each runtime.

Key Improvements:

• Node.js: Uses native file system APIs for better performance
• Cloudflare Workers: Uses platform-specific APIs, avoids Node.js-only code
• Automatic selection: SDK automatically picks the right implementation
• No code changes needed: Works transparently

4. Platform-Specific Config Defaults

PR: #2437

Different default configurations for different runtimes to optimize behavior.

Changed the autoUploadDownloadFiles default configuration for the Cloudflare Workers runtime, to avoid triggering runtime errors on unsupported features.

Cloudflare Workers defaults:

{
  autoUploadDownloadFiles: false; // We don't currently support file uploads/downloads in Cloudflare Workers
}

Benefits:

• Zero config for common use cases
• Optimized for each platform's strengths
• Override defaults when needed

5. Node Buffer → Uint8Array Refactoring

PR: #2438

All node:buffer usage replaced with standard Uint8Array for universal compatibility.

Impact:

• Works in Node.js and Cloudflare Workers
• ESLint rules enforce this pattern going forward
• Better type safety with standard types
• Fully backward compatible - no code changes needed

Bug Fixes

6. Tool Fetching with Specific Version

PR: #2518

Fixed issues when executing tools with version constraints.

Before (Bug)

// This would fail or fetch wrong version
await composio.tools.execute('GITHUB_CREATE_ISSUE', {
  userId: 'user_123',
  version: '1.2.0', // Version constraint ignored
  arguments: {
    /* ... */
  },
});

After (Fixed)

// Now correctly respects version constraint
await composio.tools.execute('GITHUB_CREATE_ISSUE', {
  userId: 'user_123',
  version: '1.2.0', // Version constraint honored
  arguments: {
    /* ... */
  },
});

Test Coverage: Added 174 new test cases to prevent regression.

7. Python JSON Schema Default Values

PR: #2506

Fixed type coercion for stringified default values in JSON schemas.

Before (Bug)

# Schema with stringified default
{
  "type": "integer",
  "default": "42"  # String instead of int
}

# Would cause runtime errors

After (Fixed)

# SDK automatically coerces to correct type
{
  "type": "integer",
  "default": 42  # Properly coerced to int
}

# Works correctly

Impact: Fixes runtime errors with tools that have stringified defaults in their schemas.

8. Salesforce Type Error Fix

PR: #2426

Fixed SALESFORCE_CREATE_LEAD type error with custom_fields parameter.

Before (Bug)

# Would fail with type error
composio.tools.execute('SALESFORCE_CREATE_LEAD', {
    'user_id': 'user_123',
    'arguments': {
        'custom_fields': {
            'CustomField__c': 'value'
        }
    }
})

After (Fixed)

# Now works correctly
composio.tools.execute('SALESFORCE_CREATE_LEAD', {
    'user_id': 'user_123',
    'arguments': {
        'custom_fields': {
            'CustomField__c': 'value'
        }
    }
})

Technical Details: Implemented proper support for anyOf and allOf JSON Schema constructs in Python SDK.

Migration Guide

Step 1: Update Dependencies

@composio/openai@latest npm update @composio/anthropic@latest npm update @composio/vercel@latest
# etc. ```
</Tab>
<Tab value="pnpm">
```bash pnpm update @composio/core@latest # Update provider packages if using them pnpm update
@composio/openai@latest pnpm update @composio/anthropic@latest pnpm update
@composio/vercel@latest # etc. ```
</Tab>
<Tab value="yarn">
```bash yarn upgrade @composio/core@latest # Update provider packages if using them yarn upgrade
@composio/openai@latest yarn upgrade @composio/anthropic@latest yarn upgrade
@composio/vercel@latest # etc. ```
</Tab>
<Tab value="pip">```bash pip install --upgrade composio ```</Tab>
<Tab value="uv">```bash uv pip install --upgrade composio ```</Tab>
</Tabs>

---

### Step 2: Update Webhook Verification (Required)

<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
<Tab value="TypeScript">

**Update signature with new parameters and add `await`:**

```typescript
// @noErrors
// Before - old signature
const payload = composio.triggers.verifyWebhook({
payload: req.body.toString(),
signature: req.headers['x-composio-signature'] as string,
secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
});

// After - new signature with await and additional parameters
const result = await composio.triggers.verifyWebhook({
id: req.headers['webhook-id'] as string, // NEW
payload: req.body.toString(),
secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
signature: req.headers['webhook-signature'] as string, // header name changed
timestamp: req.headers['webhook-timestamp'] as string, // NEW
});

// Access the normalized payload and version info
const event = result.payload;
const version = result.version; // 'V1', 'V2', or 'V3'

import express from 'express';
import { Composio } from '@composio/core';

const app = express();
const composio = new Composio();

// Make route handler async
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    // New signature with all required headers
    const result = await composio.triggers.verifyWebhook({
      id: req.headers['webhook-id'] as string,
      payload: req.body.toString(),
      secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
      signature: req.headers['webhook-signature'] as string,
      timestamp: req.headers['webhook-timestamp'] as string,
    });

    // Access verified webhook data
    console.log('Webhook version:', result.version);
    console.log('Received trigger:', result.payload.triggerSlug);

    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(401).send('Unauthorized');
  }
});

import { Composio } from '@composio/core';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });

    try {
      const body = await request.text();

      // Now works in Cloudflare Workers!
      const result = await composio.triggers.verifyWebhook({
        id: request.headers.get('webhook-id') || '',
        payload: body,
        secret: env.COMPOSIO_WEBHOOK_SECRET,
        signature: request.headers.get('webhook-signature') || '',
        timestamp: request.headers.get('webhook-timestamp') || '',
      });

      // Process verified webhook
      console.log('Trigger:', result.payload.triggerSlug);

      return new Response('OK', { status: 200 });
    } catch (error) {
      return new Response('Unauthorized', { status: 401 });
    }
  },
};

# Before - old signature
event = composio.triggers.verify_webhook(
    payload=request.get_data(as_text=True),
    signature=request.headers.get('x-composio-signature'),
    secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
)

# After - new signature with additional parameters
result = composio.triggers.verify_webhook(
    id=request.headers.get('webhook-id'),           # NEW
    payload=request.get_data(as_text=True),
    secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
    signature=request.headers.get('webhook-signature'),  # header name changed
    timestamp=request.headers.get('webhook-timestamp'),  # NEW
)

# Access the normalized payload
event = result['payload']
# Check webhook version
version = result['version']  # 'V1', 'V2', or 'V3'

from fastapi import FastAPI, Request, HTTPException
from composio import Composio
import os

app = FastAPI()
composio = Composio()

@app.post("/webhook")
def webhook(request: Request):  # Still synchronous!
    # New signature with all required headers
    try:
        result = composio.triggers.verify_webhook(
            id=request.headers.get('webhook-id', ''),
            payload=request.body().decode('utf-8'),
            secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
            signature=request.headers.get('webhook-signature', ''),
            timestamp=request.headers.get('webhook-timestamp', ''),
        )

        # Access normalized payload and version info
        print(f"Webhook version: {result['version']}")
        print(f"Trigger: {result['payload']['trigger_slug']}")

        return {"success": True}
    except Exception as e:
        raise HTTPException(status_code=401, detail=str(e))

from flask import Flask, request
from composio import Composio
import os

app = Flask(__name__)
composio = Composio()

@app.route('/webhook', methods=['POST'])
def webhook():  # Still synchronous!
    try:
        result = composio.triggers.verify_webhook(
            id=request.headers.get('webhook-id', ''),
            payload=request.get_data(as_text=True),
            secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
            signature=request.headers.get('webhook-signature', ''),
            timestamp=request.headers.get('webhook-timestamp', ''),
        )

        # Process verified webhook
        event = result['payload']
        return 'OK', 200
    except Exception as e:
        return 'Unauthorized', 401

Step 3: Update Mastra Integration (If Using)

Only required if you use @composio/mastra provider

Update your code:

// Before
import { MastraProvider } from '@composio/mastra';

const provider = new MastraProvider();

// After
import { MastraProvider } from '@composio/mastra';
import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  // Your Mastra v1 config
});

const provider = new MastraProvider({ mastra });

Step 4: Test Your Integration

1. Run your test suite to catch any issues
2. Test webhook verification if you use triggers
3. Test file uploads/downloads - behavior improved but API unchanged
4. Test in your target runtime (Node.js, Cloudflare Workers, etc.)

Backward Compatibility

Fully Compatible (No Changes Needed)

The following features work without any code changes:

• ✅ All tool execution APIs
• ✅ Connected accounts management
• ✅ Authentication flows
• ✅ Custom tools
• ✅ Tool Router sessions
• ✅ File upload/download (API unchanged, implementation improved)
• ✅ All provider packages (except Mastra)
• ✅ Python SDK usage (except webhook verification)

Requires Changes

The following features require code updates:

• ⚠️ Webhook verification (TypeScript) - Must add await AND add id + timestamp parameters, update header names
• ⚠️ Webhook verification (Python) - Must add id + timestamp parameters, update header names (still synchronous)
• ⚠️ Mastra integration (TypeScript only) - Must update to v1 API

Impact Summary

Cloudflare Workers Support

This release adds support for Cloudflare Workers:

import { Composio } from '@composio/core';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const composio = new Composio({
      apiKey: env.COMPOSIO_API_KEY,
    });

    // SDK now works in Cloudflare Workers!
    const tools = await composio.tools.get('user_123', {
      toolkits: ['github'],
    });

    const result = await composio.tools.execute('GITHUB_CREATE_ISSUE', {
      userId: 'user_123',
      arguments: {
        /* ... */
      },
    });

    return new Response(JSON.stringify(result));
  },
};

Key Features Working in Cloudflare Workers:

• ✅ Tool execution
• ✅ Connected accounts
• ✅ Webhook verification
• ✅ File upload/download
• ✅ Custom tools

Testing

This release includes extensive E2E testing:

• ✅ Node.js: Both CJS and ESM compatibility tests
• ✅ Cloudflare Workers: Multiple test suites including Tool Router
• ✅ Mastra v1: Tests for both Zod v3 and v4
• ✅ File handling: Comprehensive tests for all platforms
• ✅ Webhook verification: Tests for all supported runtimes

Total new tests: 200+ test cases added across TypeScript and Python SDKs.

Getting Help

If you encounter issues during migration:

1. Check the docs: docs.composio.dev
2. Join our Discord: discord.composio.dev
3. Open an issue: github.com/ComposioHQ/composio/issues
4. Email support: support@composio.dev

What's Next

Future releases will focus on:

• 🚀 Performance optimizations
• 🔧 More platform-specific improvements
• 📚 Enhanced TypeScript types
• 🛠️ New tool integrations
• 🔐 Advanced authentication flows

Stay tuned for updates!

Version Information

TypeScript/JavaScript

• Package: @composio/core
• Version: 0.5.5+

Python

• Package: composio
• Version: 0.10.10+

New Features

Experimental Assistive Prompt Configuration

Tool Router sessions now support experimental configuration for timezone-aware assistive prompts. When you provide a user's timezone, the session returns a contextual assistive prompt that includes timezone-specific guidance.

from composio import Composio

composio = Composio()

session = composio.tool_router.create(
    user_id="user_123",
    toolkits=["github"],
    experimental={
        "assistive_prompt": {
            "user_timezone": "America/New_York",
        }
    },
)

# Access the generated assistive prompt
if session.experimental:
    print(session.experimental.assistive_prompt)

import { Composio } from "@composio/core";

const composio = new Composio();

const session = await composio.toolRouter.create("user_123", {
  toolkits: ["github"],
  experimental: {
    assistivePrompt: {
      userTimezone: "America/New_York",
    },
  },
});

// Access the generated assistive prompt
if (session.experimental) {
  console.log(session.experimental.assistivePrompt);
}

Toolkit Endpoint Method

The toolkit retrieve response now includes getCurrentUserEndpointMethod (TypeScript) / get_current_user_endpoint_method (Python) to indicate the HTTP method for the current user endpoint.

Breaking Changes

Trigger Pagination: page Replaced with cursor

The page parameter in listActive / list_active for trigger instances has been replaced with cursor for cursor-based pagination. There was a bug in earlier APIs which caused page param to be ignored, going ahead for pagination please use cursor instead.

# Before (deprecated)
triggers = composio.triggers.list_active(page=1, limit=10)

# After
triggers = composio.triggers.list_active(cursor="cursor_string", limit=10)
# Use response.next_cursor for the next page

// Before (deprecated)
const triggers = await composio.triggers.listActive({ page: 1, limit: 10 });

// After
const triggers2 = await composio.triggers.listActive({ cursor: "cursor_string", limit: 10 });
// Use response.nextCursor for the next page

Impact Summary

Migration Guide

If you are using the page parameter in listActive / list_active:

1. Replace page with cursor
2. For the first request, omit the cursor parameter or pass undefined/None
3. Use the nextCursor / next_cursor from the response for subsequent requests

Version Information

TypeScript/JavaScript

• Package: @composio/core
• Version: 0.5.4+

Python

• Package: composio
• Version: 0.10.9+

The initiate() method now only considers ACTIVE connected accounts when checking for duplicates. Previously, expired or inactive accounts would incorrectly trigger the multiple accounts error.

What Changed

When calling connectedAccounts.initiate(), the SDK now filters by statuses: ["ACTIVE"] when checking for existing accounts. This prevents expired or inactive accounts from blocking new connection creation.

Before (Bug)

// Expired accounts would incorrectly trigger ComposioMultipleConnectedAccountsError
await composio.connectedAccounts.initiate(userId, authConfigId);
// ❌ Error: Multiple connected accounts found (even if they're all expired)

After (Fixed)

// Only ACTIVE accounts are considered
await composio.connectedAccounts.initiate(userId, authConfigId);
// ✅ Works - expired/inactive accounts are ignored

Affected SDKs

• TypeScript: @composio/core
• Python: composio

Backward Compatibility

This is a bug fix with no breaking changes. The behavior now matches the expected intent of the multiple accounts check.

Version Information

TypeScript/JavaScript

• Package: @composio/core and provider packages
• Version: 0.5.3+

Python

• Package: composio and provider packages
• Version: 0.10.8+

The file handling modifiers now properly handle file_uploadable and file_downloadable properties nested within anyOf, oneOf, and allOf JSON Schema declarations. Previously, only direct child properties (and partial allOf support) were detected for file upload/download transformations.

What Changed

Before (Bug)

File properties inside anyOf, oneOf, or allOf were not detected:

// This schema's file_uploadable was NOT being processed
inputParameters: {
  type: 'object',
  properties: {
    fileInput: {
      anyOf: [
        {
          type: 'string',
          file_uploadable: true  // ❌ Not detected
        },
        {
          type: 'null'
        }
      ]
    }
  }
}

After (Fixed)

File properties are now correctly detected and processed at any nesting level:

// Now properly detected and transformed
inputParameters: {
  type: 'object',
  properties: {
    fileInput: {
      anyOf: [
        {
          type: 'string',
          file_uploadable: true  // ✅ Detected and processed
        },
        {
          type: 'null'
        }
      ]
    }
  }
}

Affected Scenarios

How to Update

TypeScript/JavaScript

npm update @composio/core@latest

pnpm update @composio/core@latest

yarn upgrade @composio/core@latest

Python

pip install --upgrade composio

uv pip install --upgrade composio

poetry update composio

Backward Compatibility

This release is fully backward compatible:

• All existing code continues to work without modifications
• No migration required
• File upload/download for direct properties continues to work as before
• The fix only adds support for previously unsupported schema patterns

Impact Summary

Summary

Files involved in tool execution are now shared via presigned URLs with a default TTL (time-to-live) of 1 hour. You can customize the file TTL through your project configuration.

What changed

When tools return files (images, documents, exports, etc.), these files are now delivered as presigned URLs with a configurable TTL instead of non-expiring URLs. This provides:

• Automatic cleanup - Files expire after the configured TTL
• Configurable retention - Adjust file availability based on your application's needs

Default behavior

All files returned from tool execution now have a 1 hour TTL by default. After this period, the presigned URLs expire and files are no longer accessible.

Configuring file TTL

You can adjust the file TTL to match your application's needs.

Via Dashboard

1. Navigate to Project Settings in your Composio dashboard
2. Find the File TTL configuration option
3. Set your desired TTL value

Via API

Use the Update Project Config API to programmatically configure the file TTL:

curl -X PATCH "https://backend.composio.dev/api/v3/org/projects/config" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileTtl": 3600
  }'

Impact

Migration

No code changes are required. Your existing integrations will continue to receive file URLs as before, but these URLs will now expire after the configured TTL.

If your application stores or caches file URLs for later use, ensure you handle URL expiration appropriately by either:

• Downloading files before the TTL expires
• Re-executing the tool to obtain fresh URLs when needed
• Increasing the TTL via project settings to match your retention requirements

Version Information

TypeScript/JavaScript

• Package: @composio/core and provider packages
• Version: 0.5.1+

Python

• Package: composio-core and provider packages
• Version: 0.10.7+

The PATCH /api/v3/auth_configs/{id} endpoint now implements proper partial update semantics. Previously, omitting fields would clear them (behaving like PUT). Now, omitted fields are preserved—only explicitly provided fields are modified.

What Changed

New Capabilities

Rotate a Single Credential Field

Update just client_secret without resending client_id or other fields:

from composio import Composio

composio = Composio()

# Only send the field you want to update - other credentials are preserved

composio.auth_configs.update(
    "ac_yourAuthConfigId",
    options={
        "type": "custom",
        "credentials": {
            "client_secret": "new_rotated_secret",
        },
    },
)

import { Composio } from "@composio/core";

const composio = new Composio();

// Only send the field you want to update - other credentials are preserved
await composio.authConfigs.update("ac_yourAuthConfigId", {
  type: "custom",
  credentials: {
    client_secret: "new_rotated_secret",
  },
});

Update Tool Restrictions Without Touching Credentials

Previously, this would fail because credentials was required. Now it works:

from composio import Composio

composio = Composio()

# Update tool restrictions - credentials are automatically preserved

composio.auth_configs.update(
    "ac_yourAuthConfigId",
    options={
        "type": "custom",
        "tool_access_config": {
            "tools_available_for_execution": ["GMAIL_SEND_EMAIL", "GMAIL_READ_EMAIL"],
        },
    },
)

import { Composio } from "@composio/core";

const composio = new Composio();

// Note: TypeScript SDK currently requires credentials for custom type updates
await composio.authConfigs.update("ac_yourAuthConfigId", {
  type: "custom",
  credentials: {
    // Include existing credentials when using TS SDK
  },
  toolAccessConfig: {
    toolsAvailableForExecution: ["GMAIL_SEND_EMAIL", "GMAIL_READ_EMAIL"],
  },
});

Migration Guide

Am I Affected?

Yes, if your code relied on omitting fields to clear them.

No, if you always send complete payloads or only use PATCH to update specific fields.

How to Clear Fields Explicitly

from composio import Composio

composio = Composio()

# Explicitly clear tool restrictions with empty array

composio.auth_configs.update(
    "ac_yourAuthConfigId",
    options={
        "type": "custom",
        "tool_access_config": {
            "tools_available_for_execution": [],
        },
    },
)

import { Composio } from "@composio/core";

const composio = new Composio();

// Explicitly clear tool restrictions with empty array
await composio.authConfigs.update("ac_yourAuthConfigId", {
  type: "custom",
  credentials: {
    // Include existing credentials when using TS SDK
  },
  toolAccessConfig: {
    toolsAvailableForExecution: [],
  },
});

Raw HTTP API

For users calling the API directly:

# Rotate single credential
curl -X PATCH "https://backend.composio.dev/api/v3/auth_configs/{id}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "custom", "credentials": {"client_secret": "new_secret"}}'

# Clear tool restrictions
curl -X PATCH "https://backend.composio.dev/api/v3/auth_configs/{id}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "custom", "tool_access_config": {"tools_available_for_execution": []}}'

Version Information

TypeScript/JavaScript

• Package: @composio/core and provider packages
• Version: 0.3.4 to 0.4.0

Python

• Package: composio-core and provider packages
• Version: 0.10.4 to 0.10.5

New Features

1. Wait for Connections Property

Added waitForConnections (TypeScript) / wait_for_connections (Python) property to manage connections configuration. This allows tool router sessions to wait for users to complete authentication before proceeding to the next step.

TypeScript:

const session = await composio.toolRouter.create(userId, {
  manageConnections: {
    enable: true,
    callbackUrl: 'https://example.com/callback',
    waitForConnections: true  // NEW
  }
});

Python:

session = tool_router.create(
    user_id="user_123",
    manage_connections={
        "enable": True,
        "callback_url": "https://example.com/callback",
        "wait_for_connections": True  # NEW
    }
)

2. Session-Specific Modifier Types

Introduced new modifier types for better session-based tool execution: SessionExecuteMetaModifiers and SessionMetaToolOptions.

TypeScript:

const tools = await session.tools({
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => schema,
  beforeExecute: ({ toolSlug, toolkitSlug, sessionId, params }) => params,
  afterExecute: ({ toolSlug, toolkitSlug, sessionId, result }) => result
});

Python:

from composio.core.models import before_execute_meta, after_execute_meta

@before_execute_meta
def before_modifier(tool, toolkit, session_id, params):
    return params

@after_execute_meta  
def after_modifier(tool, toolkit, session_id, response):
    return response

tools = session.tools(modifiers=[before_modifier, after_modifier])

3. Dedicated Method for Tool Router Meta Tools

Added getRawToolRouterMetaTools (TypeScript) / get_raw_tool_router_meta_tools (Python) method in the Tools class for fetching meta tools directly from a tool router session.

TypeScript:

const metaTools = await composio.tools.getRawToolRouterMetaTools('session_123', {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
    // Customize schema
    return schema;
  }
});

Python:

meta_tools = tools_model.get_raw_tool_router_meta_tools(
    session_id="session_123",
    modifiers=[schema_modifier]
)

Internal Improvements

1. Performance Optimization

Eliminated unnecessary tool fetching during tool router execution, resulting in faster tool execution with fewer API calls.

2. Improved Architecture

Tool router sessions now fetch tools directly from the session API endpoint instead of using tool slugs, providing better consistency and reliability.

3. Simplified Implementation

Removed redundant tool schema fetching in execution paths, using a hardcoded 'composio' toolkit slug for meta tools.

Backward Compatibility

This release is fully backward compatible:

• All existing code continues to work without modifications
• New properties are optional with sensible defaults
• New modifier types can be adopted incrementally
• Internal changes have no impact on public APIs
• No migration required

Impact Summary

All changes follow semantic versioning principles and maintain full backward compatibility.

Shortened tool enum names across 181 actions to ensure compatibility with all AI agent frameworks.

Why This Change?

Some agent frameworks have a 64-character limit on tool/function names. Several tool enums exceeded this limit, causing compatibility issues.

No Action Required

This change will not break your integration if you are using latest toolkit versions or fetching tools dynamically. The SDK automatically resolves the correct tool names.

Migration

If you're referencing any affected tool enums by their old names, update to the new shortened names.

We've introduced a new project-level security setting that allows you to require API key authentication for all MCP server requests. This opt-in feature gives you fine-grained control over who can access your MCP endpoints.

What's New

A new "Require API Key for MCP" toggle is now available in your Project Settings. When enabled, all requests to your MCP servers must include a valid Composio API key in the request headers.

How It Works

When the setting is disabled (default):

• MCP servers work without API key authentication
• Existing integrations continue to function unchanged

When the setting is enabled:

• All MCP requests must include the x-api-key header with a valid Composio API key
• Requests without a valid API key receive 401 Unauthorized
• Only API keys belonging to the same project are accepted

Request Examples

Without API key (when enforcement is enabled):

curl -X POST "https://mcp.composio.dev/{your_mcp_server_url}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# Response: 401 Unauthorized

With API key:

curl -X POST "https://mcp.composio.dev/{your_mcp_server_url}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# Response: 200 OK

Enabling the Setting

Via Dashboard

1. Navigate to Project Settings
2. Go to the Project Configuration tab
3. Find the "Require API Key for MCP" toggle
4. Enable the toggle

Via API

Update your project configuration using the API:

curl -X PATCH "https://backend.composio.dev/api/v3/org/project/config" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{"require_mcp_api_key": true}'

Response:

{
  "require_mcp_api_key": true,
  "is_2FA_enabled": true,
  "mask_secret_keys_in_connected_account": true,
  "log_visibility_setting": "show_all"
}

Via Code

import requests

response = requests.patch(
    "https://backend.composio.dev/api/v3/org/project/config",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "ak_your_api_key"
    },
    json={"require_mcp_api_key": True}
)

print(response.json())

const response = await fetch(
  "https://backend.composio.dev/api/v3/org/project/config",
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ak_your_api_key"
    },
    body: JSON.stringify({ require_mcp_api_key: true })
  }
);

console.log(await response.json());

When to Use This

Enable API key enforcement when you need to:

• Prevent unauthorized access to your MCP servers
• Control which applications can interact with your MCP endpoints
• Add an extra security layer for production deployments
• Audit and track MCP server usage through API key attribution

API Reference

Get Current Setting

GET /api/v3/org/project/config

Update Setting

PATCH /api/v3/org/project/config

{
  "require_mcp_api_key": true
}

Tool execution errors now return a standardized response format across all failure types. Previously, the data field was empty on errors—now it always includes status_code and message, matching the structure of successful responses.

What Changed

All error responses from tool execution now include:

• data.status_code: HTTP status code (or null for non-HTTP errors)
• data.message: Detailed error message
• error: Same detailed message at the top level

Before vs After

Previous error response:

{
  "data": {},
  "successfull": false,
  "error": "404 Client Error: Not Found for url: ...",
}

New error response:

{
  "data": {
      "http_error": "404 Client Error: Not Found for url: ...",
      "status_code": 404,
      "message": "Resource not found: The requested item does not exist"
  },
  "successfull": false,
  "error": "Resource not found: The requested item does not exist",
}

Why This Matters

• Easier parsing: Agents and code can reliably access error details from data.message without special-casing empty data objects
• Better debugging: Detailed error messages replace generic HTTP error strings
• Consistent schema: Same response shape whether the tool succeeds or fails

Union Types Preserved in Tool Schemas

Tool schemas now use standard JSON Schema anyOf for union types, providing accurate type information for LLMs and code generators.

What Changed

Two changes affect how types appear in request/response schemas:

Before vs After

For example, the GOOGLECALENDAR_GET_CURRENT_DATE_TIME request schema changes: Previous (only a single type):

{
  "timezone": {
    "default": 0,
    "description": "Timezone specification...",
    "title": "Timezone",
    "type": "string"
  }
}

Now (Union types preserved):

{
  "timezone": {
    "anyOf": [
      { "type": "string" },
      { "type": "number" }
    ],
    "default": 0,
    "description": "Timezone specification...",
    "title": "Timezone"
  }
}

Similarly, nullable fields like page_token in GOOGLECALENDAR_LIST_CALENDARS:

Previous:

{
  "page_token": {
    "default": null,
    "description": "Token for the page of results to return...",
    "nullable": true,
    "title": "Page Token",
    "type": "string"
  }
}

Now:

{
  "page_token": {
    "anyOf": [
      { "type": "string" },
      { "type": "null" }
    ],
    "default": null,
    "description": "Token for the page of results to return...",
    "title": "Page Token"
  }
}

Why This Matters

• Accurate schemas: LLMs and code generators see the full set of allowed types
• Better validation: Input validation can now correctly accept all valid types, not just the first one

We've deprecated the BEARER_TOKEN auth scheme for the following 19 toolkits:

• Airtable
• Discord
• Discordbot
• Gmail
• Google Classroom
• Google Search Console
• Google Calendar
• Google Docs
• Google Drive
• Google Slides
• Google Super
• Instagram
• Ntfy
• Sapling AI
• Slack
• Slackbot
• Tawk To
• TikTok
• Twitter

Recommendation

For these toolkits, we recommend using alternative auth schemes (for example, OAUTH2, API_KEY, or other toolkit-supported schemes) instead of BEARER_TOKEN.

Backward compatibility (explicit)

This change is fully backward compatible:

• Existing auth configs and connected accounts created with BEARER_TOKEN will continue to function.
• Creating new auth configs and connected accounts with BEARER_TOKEN will continue to work (e.g., via API/SDK).
• To discourage new usage, BEARER_TOKEN auth configs / connected accounts will not be displayed in the UI for these toolkits.

The /api/v3/tools/execute/proxy endpoint now supports binary data for both file uploads and downloads.

File Uploads (binary_body)

To upload a file via the proxy, use the binary_body field in your request payload. This supports two approaches: specifying either a URL pointing to the file or providing the base64-encoded content directly.

Upload File via URL

curl --location 'https://backend.composio.dev/api/v3/tools/execute/proxy' \
  --header 'accept: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint": "/upload-endpoint",
    "method": "POST",
    "connected_account_id": "<CONNECTED_ACCOUNT_ID>",
    "binary_body": {
      "url": "{URL_TO_THE_FILE}"
    }
  }'

Upload File via Base64 Content

Supported up to 4MB file size.

curl --location 'https://backend.composio.dev/api/v3/tools/execute/proxy' \
  --header 'accept: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint": "/upload-endpoint",
    "method": "POST",
    "connected_account_id": "<CONNECTED_ACCOUNT_ID>",
    "binary_body": {
      "base64": "JVBERi0xLjQKJ...<base64_data>...",
      "content_type": "application/pdf"
    }
  }'

File Downloads (binary_data)

When the proxied request returns a binary response (for example, a PDF or image), the proxy automatically uploads the file to temporary storage, and you receive a signed URL in the binary_data field. This enables you to download large files securely.

File Download Request

curl --location 'https://backend.composio.dev/api/v3/tools/execute/proxy' \
  --header 'accept: application/json' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint": "{YOUR_ENDPOINT}",
    "method": "GET",
    "connected_account_id": "{YOUR_CONNECTED_ACCOUNT_ID}"
  }'

File Download Response

{
  "data": {},
  "binary_data": {
    "url": "url to the file",
    "content_type": "content type of the file",
    "size": "size of the file",
    "expires_at": "expires at of the file"
  },
  "status": "status code of the response",
  "headers": "headers of the response"
}

Summary

We'd love your feedback on the new proxy execute capabilities. If anything feels unclear or you have suggestions for improvement, please reach out.

We're introducing Webhook Payload V3 - a redesigned webhook structure that follows industry standards and provides better developer experience. This update affects how you receive trigger events via webhooks and Pusher.

What's Changing?

New Webhook Structure

We're adopting the Standard Webhooks specification for better consistency and reliability.

Headers

A new header will identify the webhook version:

x-composio-webhook-version: V3

Payload Structure

The payload structure is being reorganized to separate Composio metadata from trigger data:

Before (V2):

{
  "log_id": "log_TpxVOLXYnwXZ",
  "timestamp": "2025-12-23T13:06:07.695Z",
  "type": "gmail_new_gmail_message",
  "data": {
    "connection_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "connection_nano_id": "ca_xYz9AbCdEfGh",
    "trigger_nano_id": "ti_JZFoTyYKbzhB",
    "trigger_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
    "user_id": "usr-demo-12a3b4c5...",
    // ... actual trigger data mixed with metadata
  }
}

After (V3):

{
  "id": "msg_a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "timestamp": "2025-12-23T13:06:07.695Z",
  "type": "composio.trigger.message",
  "metadata": {
    "log_id": "log_TpxVOLXYnwXZ",
    "trigger_slug": "GMAIL_NEW_GMAIL_MESSAGE",
    "auth_config_id": "ac_aCYTppZ5RsRc",
    "connected_account_id": "ca_cATYssZ5RrSc",
    "trigger_id": "ti_JZFoTyYKbzhB",
    "user_id": "pg-test-86c9fc84..."
  },
  "data": {
    // Clean trigger data without Composio metadata
  }
}

Key Improvements

1. Metadata Separation: Composio-specific fields (connection IDs, trigger IDs, user IDs) are now in a dedicated metadata object
2. Clean Data: The data field now contains only the actual trigger payload without infrastructure metadata
3. Standardized Type Field: The type field now follows a consistent format (composio.trigger.message) instead of trigger-specific names like gmail_new_gmail_message
4. Trigger Slug in Metadata: The trigger slug (e.g., GMAIL_NEW_GMAIL_MESSAGE) is now available in metadata.trigger_slug for easy identification
5. Standards Compliance: Follows Standard Webhooks specification for better interoperability
6. Consistent Structure: Same payload structure for both webhooks and Pusher channels

Migration Guide

Updating Your Webhook Handlers

If you're accessing Composio metadata fields, update your code:

# Before (V2)
trigger_type = payload["type"]  # "gmail_new_gmail_message"
connection_id = payload["data"]["connection_id"]
trigger_id = payload["data"]["trigger_id"]
message_text = payload["data"]["message_text"]

# After (V3)
trigger_type = payload["type"]  # "composio.trigger.message"
trigger_slug = payload["metadata"]["trigger_slug"]  # "GMAIL_NEW_GMAIL_MESSAGE"
connection_id = payload["metadata"]["connected_account_id"]
trigger_id = payload["metadata"]["trigger_id"]
message_text = payload["data"]["message_text"]

// Before (V2)
const triggerSlug = payload.type;  // "gmail_new_gmail_message"
const connectionId = payload.data.connection_id;
const triggerId = payload.data.trigger_id;
const messageText = payload.data.message_text;

// After (V3)
const webhookType = payload.type;  // "composio.trigger.message"
const triggerSlug = payload.metadata.trigger_slug;  // "GMAIL_NEW_GMAIL_MESSAGE"
const connectionId = payload.metadata.connected_account_id;
const triggerId = payload.metadata.trigger_id;
const messageText = payload.data.message_text;

Checking Webhook Version

You can detect the webhook version from headers:

webhook_version = headers.get("x-composio-webhook-version", "V2")
if webhook_version == "V3":
    # Use new structure
    metadata = payload["metadata"]
else:
    # Use old structure
    metadata = payload["data"]

Rollout Timeline

• December 2025: V3 released, opt-in via project settings
• February 15, 2026: All new organizations will default to V3
• Existing organizations: Continue using V2 by default, can opt-in to V3 anytime

How to Opt-In

1. Go to your project settings in the Composio dashboard
2. Navigate to the Webhooks section
3. Select "Webhook Payload Version: V3"
4. Update your webhook handlers to use the new structure
5. Test thoroughly before enabling in production

Benefits