SDK releases: custom toolkits in Python 0.31.0 and TypeScript 0.28.0
You can now create custom MCP toolkits for a single user or share them across your project. Both SDKs use Composio client2.0.1.Release versions
0.31.0.What’s new
- Custom MCP toolkits. Use
composio.experimental.custom_toolkits.create()in Python orcomposio.experimental.customToolkits.create()in TypeScript. Setuser_idoruserIdto a user ID for a private toolkit, or to'all'to share it across the project. Creation returns a generated slug and, when available, a connect link for a private toolkit. Store the slug and pass it toupdate()to change the name, logo, or API key input copy. TypeScript also acceptsadditionalFields.genericIdfor headers that use{{generic_id}}. - Trigger delivery and polling. Pass
typeto choose webhook or polling delivery for a trigger that supports both. Setpolling_intervalin Python orpollingIntervalin TypeScript to choose the minutes between polls. Created and listed instances include their delivery type, polling interval, and fallback reason. Trigger type metadata reports supported delivery types and whether webhook endpoint setup is required. - Session policies. TypeScript
sessionConfigs.get()preservesrequire_approvallists and accepts policy entries that contain only approval requirements. Toolkit metadata also exposesmeta.appUrlwhen the API returns it. - Anthropic compatibility. The TypeScript Anthropic provider accepts
@anthropic-ai/sdk^0.135.0.
Migration notes
- Custom toolkit registration.
upsert()still works, but warns once per process that it is deprecated. Before: register a toolkit with a caller-chosen slug throughupsert(). After: callcreate(), store its returned slug, and useupdate(slug, ...)for later metadata changes. The server URL, auth schemes, and owning user cannot change after creation; delete and create the toolkit again to change them. - Write retries. POST and PATCH requests are sent once by default. A write may complete on the server even when its response is lost, so retry only when you can prevent duplicate side effects. Reads keep their retry behavior. On the TypeScript client returned by
getClient(), opt a write into retries with that call’smaxRetriesoption. - Direct TypeScript client calls. Replace
client.request(...)withclient.get(path, options)for GET requests, retaining the relevant query and request options. For other HTTP methods, usepost,patch,put, ordelete. Resource classes,Composio.Tools-style statics, namespace-member types,Composio.Composio, andComposio.DEFAULT_TIMEOUTare removed. Import types from@composio/client/resources/*without.jsor.mjssuffixes, and use indexed access for nested types. - Session config search. TypeScript
sessionConfigs.list()ignores the deprecatedsearchoption and warns when you set it. Filter the returneditemsby name instead.
Bug fixes
- Local upload MIME types. Files uploaded from local paths use the MIME type of their extension instead of always using
application/octet-stream. Python and TypeScript use the same extension table. Files supplied asFileobjects or URLs keep the MIME type they carry. - Python downloaded filenames. Files downloaded from extensionless URLs use the extension corresponding to a known response MIME type, including formats such as CSV and PowerPoint. Unknown MIME types leave the generated filename extensionless.
- Python schema defaults. Default coercion handles schemas whose
typeis a list, including nullable types. - Python Gemini execution. Manual function-call handling uses the user or session you supply, and rejects ambiguous ownership instead of choosing the last user to fetch tools. See the Gemini provider fix.
- TypeScript session authorization. Sessions returned by
create()anduse()accept the already-supportedexperimentalauthorization options in their public types.
Gemini Manual Function Calling Runs as the Right User
With Automatic Function Calling turned off,GeminiProvider.handle_response(response) in composio-gemini executed each function call with the executor stored by the latest tools.get() or session.tools() for that tool. When one Composio instance served several users, a call from Alice’s conversation could run with Bob’s user_id and connected account, and Bob’s result went back into Alice’s chat. The callables used by Automatic Function Calling were not affected.Bug Fixes
- Gemini (
composio-gemini):handle_responseacceptsuser_id=orsession=, with the same names asGoogleProvider.handle_responseincomposio-google. Each call runs exactly as the tool fetched for that user or Tool Router session would: validated against the schema from that fetch (including its schema modifiers), with the modifiers given totools.get(), and through the session’s routing, so local custom tools in aCOMPOSIO_MULTI_EXECUTE_TOOLbatch run in process. - Without a user or session,
handle_responsekeeps working for a process that has fetched tools for a single user or session. Once the provider has wrapped tools for more than one, it raises aValueErrorinstead of picking one, and executes nothing.
Python SDK 0.29.1: certificate and dependency hardening
This patch release hardens how the Python SDK and its providers resolve dependencies. It has no API changes.Release versions
0.29.1.What’s changed
certifi>=2026.10.19is now required. That bundle removes the emSign ECC Root CA - G3 root after eight eMudhra intermediate keys were compromised. Older bundles still trust certificates issued under it.- Third-party dependencies have upper bounds. Each range stops before the first major version that wasn’t released yet when the cap was set, or before
1.0for packages still on0.x. A future major line can’t install until the SDK raises the cap. Ranges can still span majors that already exist:openai>=2.48.0,<4allows 2.x and 3.x, andanthropic>=0.120.0,<3allows 0.x through 2.x.certifistays uncapped so CA bundle updates always install. pysheris pinned to1.0.8. The trigger client depends on it, and it has had no release since 2022. Its transport is capped atwebsocket-client<2.- Releases come from a locked build. Packages are built only from locked dependencies and published with PyPI trusted publishing, so each file on PyPI carries an attestation linking it to the GitHub workflow that built it.
Python SDK 0.29.0: toolkit warnings and provider argument fixes
The Python SDK now warns when the API reports that a toolkit version you use is deprecated. This release also fixes tool argument serialization and preserves more of your schemas across providers.Release versions
0.29.0.What’s new
- Toolkit deprecation warnings. The SDK warns once per process for each deprecated toolkit version reported through the
Composio-Deprecated-Toolkitsresponse header. The warning names the version, its sunset date, and how to pin a newer version. See toolkit versioning.
Migration notes
If you constructHttpClient directly, replace the credential keywords with an auth value:Before: HttpClient(provider="openai", api_key=key).After: HttpClient(provider="openai", auth=ProjectAuth(key)), importing ProjectAuth from composio_client.For organization and project routing, replace scope headers with scope=Scope(organization_id=org_id, project_id=project_id), importing Scope from composio_client. Remove default_query from direct client construction.Bug fixes
- Pydantic aliases. Tool execution serializes Pydantic arguments with their declared aliases, including nested models and explicit serialization aliases.
- Provider arguments. AutoGen and Google ADK preserve and validate free-form arguments instead of dropping them. OpenAI Agents preserves the source schema’s
additionalProperties. See the provider behavior changes and limitations. - Google ADK nested arrays. The provider preserves nested array item schemas instead of replacing them with a flat string schema.
SDK releases: session hooks in Python 0.30.0 and TypeScript 0.27.0
You can now attach hooks to a session to block a tool call before it runs or block its result before your agent sees it.Release versions
0.30.0.What’s new
- Session hooks. Pass
hookswhen you create or update a session. Hooks can run before execution or after execution, and can apply to selected toolkits. Updatinghooksreplaces the whole list;Nonein Python ornullin TypeScript removes every hook. You cannot combinehookswithexperimental.session_config_idin Python orexperimental.sessionConfigIdin TypeScript in the same call. - Hook outcomes. Session execution returns
result_type="blocked"in Python orresultType: 'blocked'in TypeScript when a hook blocks a call or result. The response contains emptydata, the hook’s message inerror, andblock_reasonorblockReason. When hooks apply, inspecthook_resultsorhookResultsfor their outcomes. Provider integrations return blocked execution as a failed tool call with the hook’s message.
Migration notes
In Python, replace direct access to a proxy response’sstatus with a result-type check:Before: print(response.status).After: print(response["status"] if response["result_type"] == "completed" else response["message"]).In TypeScript, make the equivalent check:Before: console.log(response.status).After: console.log(response.resultType === 'completed' ? response.status : response.message).This applies to session.proxy_execute() and ctx.proxy_execute() in Python, and session.proxyExecute() and ctx.proxyExecute() in TypeScript.Bug fixes
- Python custom-tool annotations.
@composio.experimental.toolreports unresolved input annotations when you register the tool, with the affected parameter and the original resolution error. - Anthropic provider dependencies. The TypeScript Anthropic provider removes its unused
@mastra/mcppeer dependency, avoiding unrelated packages during installation.
TypeScript SDK 0.26.0: toolkit warnings and provider schema fixes
The TypeScript SDK now warns when the API reports that a toolkit version you use is deprecated. This release also preserves more of your tool schemas and arguments across providers.Release versions
What’s new
- Toolkit deprecation warnings. The SDK warns once per process for each deprecated toolkit version reported through the
Composio-Deprecated-Toolkitsresponse header. The warning names the version, its sunset date, and how to pin a newer version. See toolkit versioning. - Zod v4 schema builder. Import
jsonSchemaToZodorjsonSchemaToZodShapefrom@composio/json-schema-to-zod/v4to build classic Zod v4 schemas. The root entry continues to build Zod v3 schemas. The v4 builder requires Zod4.1.13or newer and preserves schema annotations in metadata forz.toJSONSchema(). - Provider schema preservation. The TypeScript Vercel and LlamaIndex providers now give the model the tool’s JSON Schema directly, preserving keywords such as
format,contentEncoding, andcontentMediaType. Claude Agent SDK uses the new Zod v4 builder to preserve those annotations. Existing tool argument validation stays in place.
Migration notes
- TypeScript client access. Read credentials from
composio.getConfig()instead ofcomposio.getClient().apiKey,.userApiKey, or.orgApiKey. The client also removes.logger. ItsbaseURL,maxRetries,timeout, andlogLevelare read-only; derive a client withwithOptions()to change them. For example, replacecomposio.getClient().maxRetries = 0withconst client = composio.getClient().withOptions({ maxRetries: 0 })and use the derived client for those calls. - TypeScript custom headers. Replace
COMPOSIO_CUSTOM_HEADERSwith the SDK’sdefaultHeadersoption. Credential and scope headers indefaultHeadersorcreateSession({ headers })are folded into SDK configuration and no longer appear undergetConfig().defaultHeaders. Supply at most one ofx-api-key,x-user-api-key, orx-org-api-key; multiple credential headers now throw. Per-call client headers cannot override credentials or scope. WithapiKey: nulland only an organization API key, API calls, trigger authorization, andsession.mcp.headersnow consistently carryx-org-api-key. - Vercel tool schemas.
tool.inputSchemais now an AI SDKSchema. Replace directtool.inputSchema.safeParse(value)calls withasSchema(tool.inputSchema).validate(value), importingasSchemafromai. - Claude Agent SDK and Zod v4. Upgrade Zod to
4.1.13or newer before upgrading@composio/claude-agent-sdk. Older Zod v4 versions do not provide the shared metadata registry the builder needs. - Deprecated TypeScript connection data. For
customConnectionDatawithS2S_OAUTH2, supplyval.access_token, which the API requires.
Bug fixes
- Strict TypeScript tool schemas. OpenAPI
nullableis converted into a nullable type or a null branch. Unsupported string formats, includinguri, custom formats, andpath, are removed before strict requests reach the model provider. This prevents a single tool schema from causing the whole request to fail. - String argument validation. TypeScript checks a string as base64 only when its
contentEncodingisbase64. Fields withformat: "binary"or another encoding, such asbase16, accept plain strings instead of being rejected as invalid base64. - Zod v3 validation paths. Errors inside nested object properties report each property name once, including errors from
patternProperties,additionalProperties, andoneOf.
CLI 0.5.0 exits 1 on failed executions and runs composio execute through the Composio Dashboard
CLI 0.5.0 is a minor release because of one breaking change: commands that failed but exited 0 now exit 1. It also fixes staging and custom-backend logins, and sends composio execute through the Composio Dashboard. You don’t need to log in again or change any configuration.Release versions
Breaking changes
- Failed executions exit 1.
composio executenow exits 1 when a tool execution fails: the tool reported a failure, the Dashboard or backend couldn’t run it, or, with--parallel, any one of the calls failed. Meta tools behave the same. It used to exit 0. The{"successful": false, ...}JSON on stdout and the messages on stderr are unchanged. Incomposio run,execute()still rejects with the tool’s error message and the failed result. - Invalid input exits 1. These commands now exit 1 instead of 0 when their input is missing or invalid. They print the same message on stderr, nothing on stdout, and send no request:
composio dev auth-configs infowithout an<id>composio dev auth-configs createwith--custom-credentialsthat isn’t a JSON objectcomposio tools infowithout a<slug>composio dev triggers createwithout a<trigger-name>, or with--trigger-configthat isn’t a JSON objectcomposio dev triggers enablewithout an<id>
composio orgs switchwithout a usable key exits 1. When the stored API key is empty,composio orgs switchnow exits 1 and asks you to runcomposio login, instead of warning and exiting 0. It changes nothing either way.
Improvements
- The CLI calls the backend you logged in to.
composio loginrecords the backend that issued your key, but commands used to call production unlessCOMPOSIO_BASE_URLorCOMPOSIO_ENVIRONMENTwas set, so a staging login failed withInvalid or revoked user API key. Those variables still win when set, and the CLI warns on stderr when one sends your stored key to a different backend.composio executeuses the Dashboard recorded with the same login. A rejected key now prints the command to log in again. - Unmatched
--accountis a usage error. When--accountmatches no connected account,composio executeandcomposio proxyprint one line on stderr and exit 1, instead of a crash report. composio executegoes through the Dashboard. Single executions,--parallelexecutions, and meta tools all use the Dashboard athttps://dashboard.composio.dev. Output, error details, connection tips, and--jsonshapes stay the same. If the backend is unavailable, the CLI shows the Dashboard’s error message. If your network restricts outbound hosts, allowdashboard.composio.devas well asbackend.composio.dev. Every other command, includingcomposio dev playground-execute, still calls the backend API.- Executions are sent once. The CLI sends each execution request once, without retrying or following redirects. After 15 minutes it stops waiting and reports that the tool may still have run.
- Custom deployments. If you set
COMPOSIO_BASE_URLwithoutCOMPOSIO_WEB_URL,composio executekeeps calling that backend. To use a deployment’s Dashboard, set both.COMPOSIO_WEB_URLmust be anhttps://URL without credentials, a query string, or a fragment (http://is accepted only forlocalhost). Otherwisecomposio executefails before sending anything. - Telemetry install ID. When telemetry is enabled,
composio executesends the CLI’s anonymous install ID, the random UUID stored in~/.composio/analytics.json, to the Dashboard in anx-cli-install-idheader. The header is never sent to the backend API. It isn’t sent when you setCOMPOSIO_CLI_TELEMETRY_DISABLED,TELEMETRY_DISABLED,COMPOSIO_DISABLE_TELEMETRY, orCI. - Clearer
composio linkmessages.composio linkandcomposio dev connected-accounts linkreword their usage errors and their waiting and timeout lines on stderr. Exit codes and the JSON on stdout are unchanged. - API client. The CLI uses
@composio/client2.0.0-rc.19. Commands are unchanged.
Free-Form Arguments Reach Execution in AutoGen, Google ADK, and OpenAI Agents
A tool argument that accepts arbitrary keys, such as an object with noproperties, additionalProperties: true, or patternProperties, could reach your tool as {} in the Python AutoGen and Google ADK providers. No input error was raised, so the tool ran with different arguments from the ones the model sent.LangChain, LangGraph, and CrewAI were fixed in Python 0.19.0 (see Free-Form Object Arguments Are Preserved Across SDKs). This release covers the remaining agentic providers.Bug Fixes
- AutoGen (
composio-autogen): both runtime paths,autogen_coretools and AG2’sregister_tools, now pass every key the tool schema allows to execution and validate it with the same rules as LangChain and CrewAI. The advertised tool schema now marks the top-level object as open when the source schema does. - Google ADK (
composio-google-adk): top-level keys the tool schema allows are no longer filtered down to named parameters, and arguments are validated before execution. - OpenAI Agents (
composio-openai-agents): the advertised top-level schema keeps the source’sadditionalPropertiesinstead of always setting it tofalse. A schema that declares no properties is advertised as open, matching the TypeScript provider.
Behavior Change for AutoGen and Google ADK
- An unknown top-level key on a schema that declares properties and omits
additionalPropertiesis rejected instead of dropped. - A value of the wrong type, such as
"5"for an integer, is rejected instead of converted. - An optional argument the model leaves out is no longer sent as
"",0, or{}. The schema’s declared default applies instead. - An invalid
patternPropertiesor schema-valuedadditionalPropertiesraises when the tool is wrapped.
Known Limitation
On Google ADK and on AutoGen’s AG2register_tools path, the tool declaration is still built from named parameters. A tool whose whole argument object is free-form is therefore not advertised to the model as open, so the model may not send those keys. Free-form objects nested under a declared argument work on every provider.Session tool approvals, Python 3.15 support, and CLI request fixes
You can now require approval before selected session tools run and send the answers back through either SDK.Release versions
0.28.0.What’s new
- Session tool approvals. Set
requireApproval(require_approvalin Python) on session toolkit, tool, or tag filters. When a call needs input, catchComposioToolInputRequiredError(ToolInputRequiredErrorin Python), display itsinputRequests(input_requests), and wait for the person’s answers. Repeat the call withinputResponsesandrequestState(input_responsesandrequest_state). Forward decline and cancel answers unchanged. Both tool execution and meta-tool execution support this flow. - MCP approval fallback. Set
experimental.noElicitationSupportFallback(experimental.no_elicitation_support_fallbackin Python) todenyorallowto choose what happens when the MCP client cannot ask for approval. - Python versions. The Python SDK supports Python 3.11 through 3.15.
Migration notes
Before:session.executeMeta(slug, args, requestOptions).After: session.executeMeta(slug, args, undefined, requestOptions).Both SDKs now pass product and runtime identity through the API client’s identity option. Remove identity headers such as x-source, x-framework, x-sdk-version, and x-client-* from custom default or request headers: the client now rejects attempts to override its identity headers instead of silently replacing them. In TypeScript, Cloudflare Workers and Vercel Edge with Node.js compatibility enabled report their actual runtime, and custom provider names that cannot be sent as header values are reported as unknown.Bug fixes
- TypeScript trigger subscriptions.
triggers.unsubscribe()closes the realtime connection, cancels an in-progress subscription, and does not create a connection when called before subscribing. Concurrent subscriptions share a connection. Rejected asynchronous trigger handlers are logged without becoming unhandled rejections. - CLI request handling. Only API reads that are safe to repeat are retried. Mutating calls are sent once, preventing a timeout from repeating a side effect. Commands validate the response fields they use while tolerating unrelated API changes.
- CLI command errors. Commands that require login report a consistent usage error. Project-resolution failures retain their specific error type. The
devgroup’s--user-idand--project-nameflags work before or after the subcommand, and unsupported flags fail with a usage error.
Show the Connect Link in Spanish or Simplified Chinese
The Connect Link can now show its text in Spanish or Simplified Chinese. Add?locale=es or ?locale=zh-CN to the redirect_url before you send it to the user, and the whole flow, including the success and failure screens, uses that language.For now, only en, es, and zh-CN are supported. Links without locale, or with any other value, show English. See White-labeling authentication → Language for examples.Python SDK 0.27.0 and TypeScript SDK 0.24.0 add Session meta-tool execution and Instant search prices
You can now execute Composio meta tools directly from a Session in both SDKs, enable proxy execution when creating or updating a Session, and request Instant tool prices in search results.Release versions
0.27.0. This release also publishes @composio/experimental 0.2.8, @composio/anthropic 0.11.5, @composio/claude-agent-sdk 0.12.2, @composio/langchain 0.11.2, @composio/mastra 0.10.6, and @composio/openai-agents 0.11.2.What’s new
- Execute meta tools. Use
session.executeMeta()in TypeScript orsession.execute_meta()in Python to run aCOMPOSIO_*meta tool with a slug and optional arguments. The response includesresultType(result_typein Python), and input requests raiseComposioToolInputRequiredError(ToolInputRequiredErrorin Python). Calls are sent once without retries. The exportedToolRouterSessionMetaToolSlugtype lists the accepted slugs. - Configure Session proxy execution. Pass
proxyExecute: truewhen creating a TypeScript Session, orproxy_execute=Truein Python, to exposeCOMPOSIO_PROXY_EXECUTE. The option also accepts an object withenable, and you can change it throughsession.update(). Set it tofalse(Falsein Python) to disable the sandbox’sproxy_execute()helper too. Set it tonull(Nonein Python) when updating to remove the stored setting. The API rejects a disabled proxy setting combined with an enabled sandbox proxy setting at creation. - Inspect Instant prices in search. The experimental
instant.returnPricesInSearchSession option (instant.return_prices_in_searchin Python) returns each Instant tool’s price undertoolkitConnectionStatuses[].instantAccount.prices(toolkit_connection_statuses[].instant_account.pricesin Python). You can set it when creating or updating a Session. - Filter by hint tags. Session tag filters accept
createHintandupdateHint.
Bug fixes
- Python trigger listeners.
wait_forever()keeps waiting through recoverable network drops while Pysher reconnects, and returns when the connection worker stops.restart()requests a reconnect on the running worker.
Improvements
- API client types. The updated API clients accept a
nullid_tokenin OAuth connection data types. TypeScript’s SDK connection-state validation is unchanged. - Provider compatibility. TypeScript provider peer ranges accept Anthropic SDK
0.132and OpenAI Agents0.20. The experimental provider also accepts Pi coding-agent1.x.
Deprecations
composio.mcp.generate() now warns once that its URLs depend on the deprecated include_composio_helper_actions query parameter. Use a Session’s MCP endpoint instead.Python SDK 0.26.0 and TypeScript SDK 0.23.0 report input requests and stop retrying Session executions
Both SDKs move to the2.0.0-rc.11 API client. A Session tool that needs user input now raises a typed error instead of returning an empty result, Session executions are no longer retried, and tool schema patterns run on a linear-time regex engine.Release versions
@composio/anthropic 0.11.4, @composio/json-schema-to-zod 0.3.4, and @composio/experimental 0.2.7. The Python provider packages are released at 0.26.0.Breaking changes
TypeScriptToolRouterSessionConfig(session.config, the result ofsession.update()) andToolRouterSessionConfigHistoryConfig(session.listConfigHistory()) are the client’s own types.instantis always present, asfalseor the policy object.- In those types,
toolkitsand eachtoolsentry can be a{ require_approval }-only object, so a check forenabledordisabledno longer covers every case.tagscan carryrequire_approval, and the config can carryproxy_execute. - The Session config is returned as the API sent it. The SDK no longer validates
instantat runtime or removes apremium_usagekey. ToolRouterSessionExecuteResponserequiresresultType. A customToolCallSessionpassed to a provider must return it fromexecute(), becausesuccessfulis no longer derived fromerror.ToolRouterInstantResponseSchemaandToolRouterInstantResponseare no longer exported. UseToolRouterSessionConfig['instant'].
session.execute().instant_chargeandsession.config.instantare models, not dictionaries.ToolRouterSessionExecuteResponseandToolRouterSessionSearchResponsealias the client’s classes.ToolRouterInstantResponse,ToolRouterInstantResponseEnable,ToolRouterInstantResponseDisable, andToolRouterInstantAccountare gone fromcomposio.core.models.tool_router_session. The input typesToolRouterInstantConfig,ToolRouterInstantEnable, andToolRouterInstantDisableare unchanged.ToolExecuteParamsno longer hasallow_tracingandentity_id, which were never sent to the API.
- In Python, replace dictionary access on Instant charges and the Session
instantpolicy with attribute access. - In TypeScript, return
resultType('completed'or'failed') from any customToolCallSession.execute(). - Where you inspect a Session config, handle
toolkitsandtoolsentries that only carryrequire_approval.
What’s new
- Input requests. A Session tool can ask for user input, such as an approval, instead of running.
session.execute(),session.proxyExecute()(session.proxy_execute()in Python), provider-wrapped Session tools, and the helpers passed to custom tools raiseComposioToolInputRequiredErrorin TypeScript andToolInputRequiredErrorin Python. The error carries the questions oninputRequests(input_requests) and the opaque continuation state onrequestState(request_state), which is kept out of logs and serialized output. Nothing was executed and the call is not retried. The SDKs do not submit answers yet. - Execution result type. Session executions report
resultTypein TypeScript andresult_typein Python ascompletedorfailed. Read it rather thanerrorto tell a failure from a success: a failed execution can carry an emptyerror, and it is no longer reported as successful. user_idon direct proxy calls.composio.tools.proxyExecute()acceptsuserIdand Python’scomposio.tools.proxy()acceptsuser_id. Projects with 2FA enabled check it against the connected account and may require it.- Python Anthropic tool caching.
AnthropicProvider(cache_tools=True)attaches Anthropic’s ephemeralcache_controlto the last tool definition, which caches the whole tool list. - Python OpenAI Agents strict mode.
OpenAIAgentsProvider(strict=True)registers tools with schemas normalized for structured outputs. A schema strict mode cannot express falls back to the non-strict path.
Bug fixes
- Session executions are sent once.
session.execute(),session.proxyExecute(), provider-wrapped Session tools, and the custom tool helpers no longer retry after a timeout, a connection error, or a408,409,429, or5xxresponse, so a retry cannot repeat a side effect such as sending the same email twice. This matchestools.execute()andtools.proxyExecute(). The experimental workbench helperrun_composio_toolfollows the same rule and reports failed and input-required answers as errors. - Linear-time schema patterns. Tool schema
patternandpatternPropertiesregexes run on a linear-time engine in both SDKs, so a pattern such as^(a+)+$can no longer hang argument validation. ApatternPropertieskey that needs lookaround or a backreference fails conversion. - Strict mode with optional enums. Optional
enumandconstparameters,typebesideanyOf, and$refwith sibling keywords are wrapped whole inanyOfwith anullbranch, so the model can omit them under strict mode. - Portable file names. Server-provided file names with characters Windows reserves, such as
report_2026-09-29T10:30:00.csv, are saved with those characters replaced instead of being rejected. Default saves never overwrite an existing file. Python automatic downloads follow validated redirects again. - Object-rooted tool schemas in TypeScript. Parameters that use
anyOf,oneOf,allOf, or$refconvert to aZodObjectagain, so the LangChain, Vercel, LlamaIndex, and Claude Agent SDK providers send a top-leveltype: "object". - Anthropic cache breakpoints in TypeScript.
cacheTools: trueplaces a single breakpoint on the last tool and no longer markstool_resultblocks, staying within Anthropic’s limit of 4 breakpoints per request. - Gemini automatic function calling in Python. Tools with optional or constrained arguments run through automatic function calling again.
Improvements
- Both SDKs send product identity, product version, language, and runtime version with API requests.
@composio/coreand@composio/slimare identified separately.
Python SDK 0.25.0 and TypeScript SDK 0.22.0 align Instant Sessions
Both SDKs now use the Instant Session and account contracts. Tool execution and usage responses expose exact Instant charges, and provider helpers can execute tools through a supplied Tool Router Session.Release versions
Instant Sessions and charges
- Configure Instant access with
instantand request execution charge details withinstant.returnInstantChargein TypeScript orinstant.return_instant_chargein Python. The formerpremium_usageandreturn_premium_chargenames are replaced by the Instant contract. - Read
instantChargein TypeScript orinstant_chargein Python from Session execution results. Project usage summaries expose the exact USD amount as a string; charged tool logs includemetadata.instant_charge. - Select an Instant account with
instant_accountin the Session API contract. Session search results describe available Instant tools throughinstantAccountin TypeScript orinstant_accountin Python.
Provider helpers and fixes
- Google, Cloudflare, and OpenAI Responses helpers in TypeScript, and the Google Gemini helper in Python, accept a Tool Router Session for execution. Existing user ID calls continue to use direct execution.
- TypeScript
ConnectionRequest.statusnow follows the result ofwaitForConnection(), and telemetry records calls towaitForConnection(). - The OpenAI provider no longer includes Assistants API helpers. Move Assistants integrations to the Responses API and
OpenAIResponsesProviderfrom@composio/openai.
Don’t store data is now Zero Data Retention
The Don’t store data option under Log storage is now Zero Data Retention (ZDR). You manage it as an organization add-on in Organization Settings > Billing > Add-ons. Every project kept its setting, so projects that had Don’t store data on now show ZDR on.What’s new
- An organization admin can turn on ZDR for all projects at once. Admins can also turn it on or off for one project in Project Settings > General.
- ZDR is available on paid plans for a usage-based price and included on Enterprise, where new projects start with ZDR on. Hobby plan projects that already had Don’t store data keep ZDR on until an admin turns it off.
- The Zero Data Retention page lists what ZDR covers, what it does not cover, and what Composio still stores.
Python SDK 0.24.0 and TypeScript SDK 0.21.0 add Session policies and fixes
Both SDKs add experimental premium usage policies and fix default Session updates. TypeScript also adds saved Session configs and hosted-account details in search results.Release versions
Premium usage policies
SetpremiumUsage in TypeScript or premium_usage in Python when creating or updating a Session to control billed tool execution. Pass false (False in Python) to disable it, or a policy object to restrict eligible toolkits and tools. Your project must allow premium usage. Passing a policy object re-enables premium usage on a Session where it was disabled.In Python, set premium_usage.return_premium_charge to receive charge details when available. session.execute() exposes them through the typed premium_charge field on ToolRouterSessionExecuteResponse. Provider integrations and mixed local/remote multi-tool execution preserve these details. The exported PremiumCharge type includes amount, currency, and charged_by.Saved Session configs in TypeScript
- Read saved configs with
composio.sessionConfigs.list()andcomposio.sessionConfigs.get(). - Apply a saved config through
experimental.sessionConfigIdwhen creating or updating a Session. Read its source metadata throughsession.experimental.sourceSessionConfig. - Config IDs cannot be combined with inline access fields:
toolkits,tools, ortags, plusexperimental.customToolsandexperimental.customToolkitson create. Invalid combinations fail before a request is sent. - Search results expose
hostedAccount.allowedToolSlugson toolkit connection statuses for Composio hosted accounts.
Fixes
- Session updates in both SDKs:
session.update()no longer sendsexpected_config_versionby default, fixing the API’s rejection of ordinary updates. Updates use last writer wins. To request a conditional update where the API supports it, passexpectedConfigVersionin TypeScript orexpected_config_versionin Python explicitly. - File saves in both SDKs: unsafe server-supplied mount paths now raise validation errors before creating directories or writing files. This includes paths that resolve to a directory or its parent and filenames with trailing dots exposed by stripping Unicode whitespace.
- TypeScript downloads:
RemoteFile.save()validates its default destination before downloading content, so an invalid mount path fails without a network request. - Python auth configs: update, delete, enable, and disable methods now declare the client’s concrete response types, including their
successandmessagefields.
Python SDK 0.23.0 and TypeScript SDK 0.20.0 add a faster API client
Python SDK0.23.0 and TypeScript SDK 0.20.0 replace the old autogenerated client with a new handrolled one. Its lightweight HTTP transport is substantially faster while preserving the SDK APIs you already use. The client also covers more of Composio’s v3.1 API.Release versions
Faster API requests
The new client reduces request overhead without changing existing imports, types, retries, timeouts, error classes, raw responses, streaming responses, orAbortSignal support. TypeScript users also get configurable SDK logging through logger and logLevel; Python routes client deprecations through ComposioDeprecationWarning.More of the Composio API
- Project webhooks (
webhooks.subscriptionsandwebhooks.endpoints), tool execution logs, customer-managed keyring transfer keys, experimental usage metering, and experimental project-owned custom toolkits. - Connected account revocation and deferred OAuth completion.
- Toolkit bulk retrieval, changelogs, OAuth scope recommendations, and grant contexts. Toolkit auth details now include each field’s end-user visibility and the scopes an auth method always requests.
- Tool Router session configuration history through
session.listConfigHistory()in TypeScript andsession.list_config_history()in Python. userApiKeyandorgApiKeyin TypeScript, anduser_api_keyandorg_api_keyin Python, for user- and organization-scoped operations.
Safer authentication and session updates
You can now authenticate without a project key by settingapiKey: null in TypeScript or disable_api_key=True in Python, then supplying a user or organization API key. Consumer requests can be scoped with orgId and projectId in TypeScript or org_id and project_id in Python.Session MCP configuration exports only the credential and project scope used for the session request, and only when the MCP URL has the same origin as the configured Composio API. session.update() now uses the session’s last observed config version by default. Concurrent writes raise a typed conflict instead of silently overwriting a newer configuration, and nullable policy fields can remove stored overrides.connectedAccounts.refresh() is deprecated because the API deprecated its endpoint. The API also removed credential validation from refresh, so TypeScript now ignores validateCredentials and logs a warning when you set it.Auth Configs Fetch Limit Raised to 200
Improvements
- Raised the auth configs fetch limit from 50 to 200, so teams with many configured auth providers can retrieve them all in a single call without pagination.
Scoped API Keys: Tools Read Now Accepts Read-Scoped Keys
When creating a scoped API key through the API key creation flow, you can assign either read or write scope. Reading multiple toolkits at once was incorrectly requiring a write-scoped API key. This has been fixed to accept read-scoped keys as intended.Bug Fixes
- Fetching and listing tools across multiple toolkits previously required a write-scoped API key. The scope check was corrected so that read-scoped API keys are now accepted for these read operations.
Backward Compatibility
This is a backward-compatible fix. Existing API keys with write scope continue to work exactly as before. Read-scoped keys can now be used for tools read operations without needing to upgrade to write scope.Python SDK 0.22.0 and TypeScript SDK 0.19.0 add safer TypeSafe and session workflows
Python SDK0.22.0 adds a TypeSafe provider. TypeScript SDK 0.19.0 improves session and connection workflows, returns clearer errors, and strengthens network safeguards. The accompanying @composio/typesafe 0.1.1 release updates the package first published as 0.1.0 on September 17.Release versions
TypeSafe support turns Jev decisions into Composio calls
The newcomposio-typesafe package and the existing @composio/typesafe package integrate Composio tools with TypeSafe’s Jev model. They compile tools into typed questions, return a complete call, partial call, or abstention with a confidence score, and require explicit confirmation before destructive tool execution.You can also shortlist tools before a decision and apply a confidence gate when a workflow needs a minimum judgement score.TypeScript 0.1.1 rejects root schema composition that can hide required arguments, requires explicit values for prototype-named arguments, and preserves __proto__ as caller data during execution.Sessions expose more state and avoid duplicate authorization
TypeScript sessions now expose the server-returned configuration throughsession.config. session.update() returns the updated configuration, and session.ensureConnected() reuses an active connection before starting a new authorization flow.Python and TypeScript MCP updates now preserve tool-only allowlists, auth config selections, and manual connection-management intent. Python mixed local and remote multi-tool execution also preserves request order and retains completed local results when the remote request fails.Session interface yourself, add the required config member. Sessions created by the SDK already provide it.Errors are easier to handle
Tool lookup failures now distinguish a missing tool from authentication, server, and network failures. Trigger subscription setup errors can be handled through a callback instead of escaping asynchronously, and HTTP status errors in Python remain catchable asComposioError.Network safeguards cover redirects and transition ranges
Both SDKs now apply standard redirect method and body rules, remove credentials on cross-origin redirects, and reject additional IPv4, IPv6, and transition-network ranges. TypeScript also offers a strict SSRF mode for callers that require the connection to stay pinned to the validated address.The TypeScript JSON Schema converter rejects invalid or oversized regular-expression patterns with a path-aware error. Provider dependency ranges have also moved to the upstream versions used by the release test matrix.CLI 0.4.1 and SDK updates protect credentials, file transfers, and JSON Schema behavior
CLI@composio/cli 0.4.1, Python SDK composio 0.21.1, and TypeScript SDK updates strengthen credential handling and file transfers. This release also improves JSON Schema conversion across Python and TypeScript, preserves referenced definitions across TypeScript providers, and makes custom tools with shared child slugs route predictably in both SDKs.Release versions
Credentials stay private in files and logs
The CLI now creates user data, pending login sessions, and agent identity files with owner-only0600 permissions. When it encounters a credential file created by an older CLI with broader 0644 permissions, it tries to repair the mode before reading the file. A permission-repair failure does not prevent a valid file from being read. Writes remain atomic, so tightening permissions does not trade away protection against partial files.The Python and TypeScript SDKs now redact credential-shaped values at their shared log boundaries. Redaction covers structured metadata, serialized JSON, nested values, exception tracebacks, authorization headers, and URLs with sensitive query parameters. The OpenAI Responses provider also stops printing credential-bearing MCP server URLs to standard output and logs only server names at debug level.Credit to independent security researcher Syed Anas Mohiuddin for reporting the legacy CLI credential-file permission issue.File transfers have bounded sizes and consistent errors
Automatic S3 downloads in both SDKs now stop at a fixed 100 MiB limit, including responses that omit or misreportContent-Length.Python removes partial files when a download fails and maps transport or filesystem failures to ErrorDownloadingFile. TypeScript maps connection and streamed-body failures from RemoteFile to RemoteFileDownloadError, closes unused response bodies, and applies the same 100 MiB bound to buffer(), blob(), text(), and save().CLI URL uploads now use the SDK’s SSRF protections for both the source URL and the API-provided upload destination. Redirects are checked again, Node.js and Bun connect to the validated address, and internal destinations are rejected before file bytes are sent.Referenced tool schemas retain their types
The Claude Agent SDK, Google, LangChain, LlamaIndex, OpenAI Agents, and Vercel providers now resolve internal$ref and $defs references before translating a tool’s input schema. Properties reachable only through a reference previously became untyped values or dangling references in the provider-facing schema.For example, a tool schema can define an object once and reuse it:recipient.email string constraint instead of reducing recipient to an untyped value. The OpenAI Agents strict structured-output path is unchanged because OpenAI handles $defs and $ref natively, including recursive references.When a $ref has no matching entry in $defs, provider translation now falls back to a permissive object schema instead of throwing an error.$ref. Snapshot tests on translated tool definitions may need updates. Runtime calls that do not inspect or snapshot those schemas do not need migration work.Schema conversion matches JSON Schema dialects more closely
Python schema conversion and@composio/json-schema-to-zod now preserve Draft 7 acceptance across primitive, composed, referenced, conditional, and typeless schemas. Converted validators no longer accept booleans as integers, and they correctly handle tuple schemas with additionalItems, object and scalar allOf rules, internal $ref values, conditional branches, and constraints without an explicit type.@composio/json-schema-to-effect-schema now enforces the OpenAPI 3.0 and Draft 4 boolean forms of exclusiveMinimum and exclusiveMaximum, so an exclusive bound no longer accepts the boundary value.Credit to simpleqt for originally surfacing the schema conversion cases.Custom tool slugs are qualified by toolkit
Python and TypeScript sessions now distinguish custom tools by toolkit and original slug. Two custom toolkits can both define a child such asGREP, SEARCH, or VERSION without one handler replacing or hiding the other.Toolkit-qualified final slugs such as LOCAL_ALPHA_GREP and LOCAL_BETA_GREP route to the matching handler. A bare GREP alias remains available when it identifies exactly one local tool. When it is ambiguous, the SDK raises an error that lists the final slugs you can use instead of choosing a handler silently.CLI and SDK reliability fixes
- CLI spinners stay on one terminal row when a message is wider than the terminal, so
composio upgradeno longer prints hundreds of progress lines in a narrow pane. - TypeScript trigger subscriptions now apply the requested
authConfigIdfilter before invoking callbacks. - Python uploads
.jpgfiles with the standardimage/jpegcontent type while continuing to acceptimage/jpgfrom external responses.
Backward compatibility
This release does not remove or rename public APIs. Provider packages receive minor version bumps because referenced schemas now retain their real shape, which can change schema snapshots. Corrected JSON Schema conversion may also change whether previously misclassified inputs pass generated validators. Ambiguous bare custom-tool slugs now fail with the qualified alternatives rather than routing unpredictably.Granular session permissions for scoped API keys
Scoped project API keys now give you separate controls for session management and session-based execution.What’s new
- Session management controls creating, viewing, configuring, and deleting sessions.
- Session tool execution covers search, tool execution, proxy execution, and session-linked MCP access.
Python SDK 0.21.0 and TypeScript SDK 0.18.0 harden strict tool schemas and file transfers
Python SDKcomposio 0.21.0 and TypeScript SDK @composio/core 0.18.0 make strict-mode tool schemas compatible with nested and optional parameters, harden automatic file transfers, and improve reliability across providers and runtimes.SDK versions
Strict tool schemas keep optional parameters
OpenAI-compatible strict mode now normalizes schemas recursively across nested objects, unions, array items, and local references. Every object declares all properties as required and rejects undeclared properties, while fields that were optional acceptnull. Before tool execution, the SDK removes a null argument when the tool’s original schema does not accept it.Schemas that strict mode cannot represent, such as arbitrary-key objects, unsupported intersections, tuple-style arrays, or unresolved references, now fall back to non-strict mode with a warning that names the tool and incompatible path. This avoids silently narrowing the tool’s accepted input.TypeScript users can apply the same behavior directly with the new toStrictJsonSchema() and omitNullToolArguments() exports. OpenAIAgentsProvider({ strict: true }) now honors the option, and Mastra and Vercel use the same normalization rules.Python’s OpenAIResponsesProvider now accepts strict=True, emits strict: true on compatible tools, and follows the same recursive schema rules. Existing provider construction remains unchanged unless strict mode is enabled.Safer file uploads and downloads
- Automatic uploads reject sensitive paths even when a symlink hides the sensitive directory or filename.
- Empty-string file arguments are omitted instead of being sent to the API or treated as upload candidates.
- Nullable and nested file arguments retain their original structure during Python request preparation.
- TypeScript URL fetching now connects to the exact IP address that passed SSRF validation, closing a DNS-rebinding window while preserving the original hostname for HTTP and TLS verification. Redirect destinations are validated and pinned independently.
Runtime and reliability updates
- Published TypeScript packages now require Node.js 22.22.3 or newer. Package managers report unsupported runtimes during installation instead of allowing later ESM loading failures.
- Best-effort TypeScript telemetry requests now time out, so an unreachable telemetry endpoint cannot keep an SDK call pending indefinitely.
- TypeScript error subclasses now report their own names for accurate telemetry grouping.
- Python preserves explicit empty tool schemas and isolates provider dependency conflicts more reliably.
Backward compatibility
Strict mode remains opt-in. Python users who do not passstrict=True keep the existing provider behavior. TypeScript users on Node.js versions older than 22.22.3 must upgrade Node.js before installing this release.Python SDK 0.20.0 and TypeScript SDK 0.17.0 route provider tool calls through sessions
Python SDKcomposio 0.20.0 and TypeScript SDK @composio/core 0.17.0 let the OpenAI and Anthropic provider tool-call helpers execute through a supplied Tool Router session, close an SSRF gap around API-response URLs, and fix several Python file-handling issues.SDK versions
Session-aware provider tool-call helpers
Previously, calling these helpers with tools obtained fromsession.tools() still executed through the globally injected direct Tools.execute function, discarding the Tool Router session context. Session meta-tools such as COMPOSIO_SEARCH_TOOLS failed as a result. Calling session.execute() directly preserved the session but skipped provider-specific behavior, such as Anthropic’s input normalization and schema-alias restoration.The helpers now route normalized provider arguments through the supplied session when one is given, while keeping provider-specific normalization intact. Anthropic helper failures now preserve their error text in { error } results without changing successful payloads.API-response URL validation
Both SDKs already validated user-supplied URLs against SSRF before fetching them. That guard did not cover URLs that arrive inside an API response. It now does, across every response-driven fetch: tool-execution downloads, S3 presigned uploads, Tool Router session file downloads and uploads, andRemoteFile.buffer()/blob()/text()/save(). Redirect hops are re-validated on each hop, so a validated URL cannot redirect into private address space. Edge runtimes that cannot resolve DNS to check keep their current behavior for session file transfers, since a Worker’s fetch does not originate inside the caller’s network.Python file handling fixes
- Importing
composiono longer creates the local cache directory or fails on a read-only filesystem. Directory creation is deferred to the first actual file download, so environments like AWS Lambda, distroless containers, and read-only Kubernetes root filesystems can import the SDK without ever touching disk.COMPOSIO_CACHE_DIRis also now honored correctly when it is set, instead of eagerly resolving the home directory first. - File uploads to S3 presigned URLs now send the
Content-Typethe presign request was signed with on every upload path, and a rejected upload raises with its HTTP status instead of a path-only error. A malformed or negativeContent-Lengthon a fetched URL now degrades to an unknown size instead of raising. - Filesystem path construction for API-provided slugs and filenames is now centralized and rejects traversal, Windows-invalid names, invalid Unicode, and overlong encoded filenames before creating directories or writing files.
Dependency updates
Runtime dependencies across the TypeScript SDK packages and the Python core and provider packages have been refreshed.Backward compatibility
Existing user-ID based provider helper calls are unchanged. Custom provider subclasses overriding the tool-call helpers should review the updated signatures.Python SDK 0.18.2 and TypeScript SDK 0.15.0 tighten JSON Schema types and secret redaction
Python SDKcomposio 0.18.2 and TypeScript SDK @composio/core 0.15.0 redact secrets that appear inside JSON payloads in telemetry, give JSONSchemaProperty a precise recursive type, and harden several request and upload paths. @composio/openai 0.11.0 adds support for OpenAI v6 and v7.SDK versions
Secret redaction in telemetry
Telemetry error text is redacted before it leaves the process, but the key/value rule required the separator to follow the key name directly. In JSON — and in a Pythondict repr — the key’s own closing quote sits between the name and the colon, so a serialized body such as {"api_key": "sk-live-..."} never matched and the value was sent verbatim. That is the shape error messages usually carry: an API error envelope, or a rejected request body echoed back.Both SDKs now redact these values.Before:Typed JSON Schema properties
Before:@composio/json-schema-to-zod now also models the parser-supported min, max, and example JSON Schema extensions in its exported recursive schema type.What’s new
@composio/openaisupports OpenAI versions 6 and 7. The OpenAI runtime dependency in@composio/coreand@composio/slimhas been refreshed to version 7.
Improvements
- The background npm version check is now bounded by an abort timeout, so a registry outage cannot leave the request pending indefinitely.
- Sensitive upload path segments are matched using the target filesystem’s actual case sensitivity, so case-insensitive mounts cannot bypass the denylist and distinct paths on case-sensitive mounts are not over-blocked.
- Unread response bodies are released on the paths the SDK knowingly abandons: every intermediate redirect body in
ssrfSafeFetch, and the response body before throwing on a failed URL upload.
Dependency updates
Runtime dependencies across the TypeScript SDK packages and the Python core and provider packages have been refreshed.Backward compatibility
Runtime behavior is unchanged in both SDKs. The only upgrade impact is at the TypeScript type level, for consumers that readJSONSchemaProperty fields without narrowing.Free-Form Object Arguments Are Preserved Across SDKs
SDK Versions
A tool argument declared as a bare
{"type": "object"} — with no properties of its own — was rejected or silently emptied at every schema conversion boundary. This affects any tool that takes a free-form payload, such as dataset_query on METABASE_POST_API_CARD.What Changed
An object schema that names no properties is now treated as open, unless it setsadditionalProperties: false: arbitrary content is accepted and preserved, at the root, nested inside another object, and inside array items.Google Gemini schema compatibility
@composio/google now adds type: "object" to schema nodes that declare properties without a type before emitting Google GenAI function declarations. The normalization follows only schema-bearing keywords, so property maps — including a field literally named properties — and instance values under const, default, enum, and examples remain unchanged. This provider release requires @composio/core >=0.16.0 <1.0.0.Before:composio upgrade.Dynamic keys apply only where they should
Where a schema declarespatternProperties or a schema-valued additionalProperties, each key is now validated against exactly the schemas that claim it. In TypeScript a key could previously pass by satisfying an unrelated pattern instead of its own. In Python neither keyword was read at all, so dynamic keys were never validated.- Every matching
patternPropertiesentry validates its key. additionalPropertiesapplies only to keys that no declared property and no pattern matches.- A key declared in
propertiesis still checked against every pattern it matches.
patternProperties and boolean- or schema-valued additionalProperties also survive tool schema parsing; they were previously dropped before any converter could see them.Before:patternProperties or schema-valued additionalProperties schema now raises while the tool is wrapped instead of being ignored. This includes an external, anchored, or unresolvable $ref, a patternProperties key that is not a valid regular expression, or a dynamic-key subschema that is not valid Draft 7. A $ref in these schemas must be a local JSON Pointer such as #/properties/foo. The rule is transitive: a local pointer whose target carries a non-local reference raises too. A $ref-shaped value under const, default, enum, or examples is instance data rather than a reference, and is left alone.The CLI’s validator fails early on the two of those it can detect: a patternProperties key that is not a valid regular expression, and a reference inside a dynamic-key subschema that does not resolve, following local pointers transitively. Both are now reported as a schema compile failure naming the cached schema path, rather than as an input error blaming the arguments. A reference outside a dynamic-key subschema is still left to the validator, so a tool whose unused branch carries a dangling reference keeps working.Behavior Change for Python Agentic Providers
Before:additionalProperties is omitted; additionalProperties: true and schema-valued forms behave as declared.Provider argument presence is preserved
CrewAI, LangChain, and LangGraph now keep the difference between an omitted optional field and a field explicitly set toNone. JSON Schema defaults are included, while optional fields with no default stay absent. The same rules apply inside nested objects, arrays, maps, combiners, and dynamic-key values.note, the tool does not receive it. Before this release, provider serialization could add an omitted nullable field as None, or drop an explicit None, a declared default, or a dynamic extra.Not affected
composio_openai,composio_anthropic, and the other non-agentic providers. These hand the raw JSON schema to the model API and pass the returned arguments straight through, so they never build a Pydantic model from a tool schema.composio_gemini. Gemini builds a typed signature throughjson_schema_to_pydantic_type, so free-form object arguments now useDict[str, Any]instead of an empty model. It does not usejson_schema_to_model, so the unknown-key rejection above does not apply.- Provider APIs and invocation signatures. You wrap and call tools the same way. The change is limited to validated arguments passed to the tool.
Behavior Change for the Claude Agent SDK Provider
This is also what makes free-form object arguments reach execution intact through this provider: the content of a bare{"type": "object"} argument survives registration instead of being discarded with the rest of the root constraints.Not affected
@composio/vercel,@composio/langchain, and@composio/llamaindex. These already registered complete schemas, so they picked the fix up with no change.
Backward Compatibility
Accepting and preserving free-form object content is backward compatible: payloads that previously failed now succeed, and payloads that previously arrived empty now arrive complete.The two unknown-key rejections described above (Python agentic providers and the Claude Agent SDK provider) are two of the three behavior changes at call time. The third is Python dynamic-key validation: a key that used to be dropped in silence now raises aValidationError when it does not match the patternProperties or additionalProperties schema that claims it.additionalProperties: true still opts an object out of unknown-key rejection. Declaring no properties does too, unless the object sets additionalProperties: false — an explicit false closes it, and Python now raises on the unknown keys it used to drop there, the same drop-to-raise transition as the first change. Neither opt-out covers the third change: if the object carries patternProperties or a schema-valued additionalProperties, its keys are validated against those schemas. An open object with no dynamic-key constraints is unaffected by it.The remaining changes are about the schema itself rather than the arguments checked against it: an invalid dynamic-key schema now fails instead of being ignored. Only tools whose patternProperties or schema-valued additionalProperties carry such a defect are affected, and the two SDKs get there differently.In Python it is a raise while the tool is wrapped, covering an invalid reference, regular expression, or Draft 7 subschema. Neither keyword was read before, so the defect never surfaced at all and every dynamic key was dropped. A tool carrying one now fails when it is wrapped, for every caller, rather than on a particular payload.In the CLI it is a schema compile failure, covering an invalid patternProperties regular expression or an unresolvable reference inside a dynamic-key subschema. There the defect did surface, but only when validation descended into that part of the schema, and it was reported as though the arguments were at fault. A payload that stayed out of the affected branch validated against a schema that could not fully check it, and is now rejected.The CLI installer configures your shell by default
The Composio CLI installer now putscomposio on PATH for future terminals automatically. This replaces the install-only default announced in Install the Composio CLI with a POSIX shell.What’s new
- The default flow infers your shell from
$SHELLand configuresPATHfor future terminals. SetCOMPOSIO_INSTALL_SHELL=nonefor an install-only run in CI, Docker images, or when a dotfile manager owns your startup files. COMPOSIO_INSTALL_SHELL=zsh|bash|fishstill forces a specific shell, for examplecurl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh.- If your
$SHELLis not zsh, bash, or fish, the installer degrades to an install-only run and prints the command to configurePATHyourself. - Agent plugin installation and login remain opt-in.
- Re-running the installer reconciles the managed block instead of appending a second one, so repeated installs leave exactly one block per startup file.
Download verification
- Every download uses HTTPS — plain HTTP is accepted only for loopback addresses or a host you explicitly allow with
COMPOSIO_INSTALL_ALLOW_HTTP_HOST— and redirects can only ever lead to HTTPS URLs. - Official releases — the default
github.com/ComposioHQ/composiosource — must now pass checksum verification: a missingchecksums.txt, a manifest with no entry for your platform’s archive, a malformed entry, or a checksum mismatch aborts the install. Previously a missing manifest warned and continued. - On systems with no SHA-256 utility (
sha256sumorshasum), rare outside minimal containers, the installer warns that checksum verification was skipped and continues. - Overridden sources (
COMPOSIO_GITHUB_URL,COMPOSIO_GITHUB_OWNER,COMPOSIO_GITHUB_REPO, or a custom API base) stay lenient: a missing manifest or entry warns and continues, and only a checksum mismatch or malformed entry aborts.
Install the Composio CLI with a POSIX shell
The Composio CLI installer now separates the release bundle from the command you run, works with POSIXsh, and leaves shell configuration opt-in.What’s new
curl -fsSL https://composio.dev/install | shinstalls the verified release bundle in~/.composioand creates~/.local/bin/composio.- The default flow does not edit shell files, install agent plugins, or log you in.
COMPOSIO_INSTALL_SHELL=zsh|bash|fishconfigures the requested shell explicitly, for examplecurl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh.COMPOSIO_INSTALL_VERSION,COMPOSIO_BIN_DIR,COMPOSIO_QUIET, andCOMPOSIO_DEBUGgive you control over version, layout, and output.- Existing
COMPOSIO_INSTALL_DIRconfigurations keep their bundle-directory meaning.
Callback identity verification for OAuth connections
You can now add an identity check to your OAuth connections. Set a verifier URL on your project, and Composio hands each OAuth return to your server, activating the connection only after your server confirms the signed-in user is the one it was created for.It is opt-in per project and, once set, covers every OAuth connection in the project. Because it confirms the returning user, it holds however the user comes back from the provider. Turn it on in Settings → General.Learn morePython SDK 0.18.1 and TypeScript SDK 0.14.1 harden uploads and event handling
Python SDKcomposio 0.18.1 and TypeScript SDK @composio/core 0.14.1 strengthen URL upload validation and address reliability issues in file handling, trigger subscriptions, and schema conversion.SDK versions
URL upload security
- Python URL uploads now validate the canonical URL that Requests will connect to. Backslash parser differentials, malformed ports, and destinations that resolve to non-public addresses are rejected before a connection is made.
- TypeScript Tool Router session URL uploads now use the SDK’s SSRF-safe fetch path, revalidate every redirect target, and stream responses with a 100 MiB limit. Edge runtimes that cannot validate DNS fail closed for URL inputs.
- TypeScript path handling on Cloudflare Workers and other edge runtimes now avoids backtracking regular expressions that could hang on long runs of slash characters.
Python reliability and correctness
- Calling
TriggerSubscription.stop()from a trigger callback no longer deadlocks. Timed-out subscription attempts also disconnect their websocket instead of leaving a reconnecting background thread behind. - Malformed chunked trigger frames are contained at the callback boundary, so one bad frame no longer tears down an otherwise healthy subscription.
- File extensions are matched case-insensitively when inferring MIME types, so names such as
photo.PNGandscan.PDFreceive the correct content type. - JSON Schema
allOfcombinations containing an impossible schema remain rejecting through nested objects, arrays, and local definitions instead of being widened to an accepting type.
Dependency updates
Runtime dependencies across the TypeScript SDK packages and Python core and provider packages have been refreshed.Python SDK 0.18.0 hardens file uploads and provider schemas
Python SDKcomposio 0.18.0 closes URL-upload and telemetry exposure paths, aligns trigger creation with the current backend contract, and improves provider compatibility with modern tool schemas. All Python provider packages are also aligned at 0.18.0.SDK versions
File and telemetry security
FileUploadable.from_url()and Tool Router session-file imports now accept only HTTP(S) hosts whose resolved addresses are public. Redirects are rejected, and blocked inputs raiseBlockedInternalUrlError.- Error telemetry now applies best-effort redaction to error messages and stack traces before transport, covering URL queries, bearer and basic credentials, and recognized secret-like key-value pairs.
Trigger creation
triggers.create() now sends user_id to the backend rather than listing connected accounts in the SDK. When no connected_account_id is supplied, the backend selects the most recently created active connection for the user and toolkit. Self-hosted deployments need the backend version that supports this resolution.Invalid trigger slugs now raise TriggerTypeNotFound. Omitting both user_id and connected_account_id, or passing blank values for both, raises InvalidParams. When the supplied user has no matching active connection, the backend upsert error now surfaces instead of the SDK raising NoItemsFound locally.Provider and schema compatibility
- OpenAI provider tool-call handling now executes every call from the first assistant choice, including multiple calls returned in one response.
- Tool signature generation accepts list-valued JSON Schema types, unbounded
anyOfandoneOfoptions, and title-less top-level schemas. - LangChain, LangGraph, and AutoGen provider signatures now honor the configured
skip_defaultvalue. - The OpenAI Agents provider preserves valid array-item schemas instead of coercing type-less items to strings.
- Toolkit version pins are case-insensitive in both environment variables and user-provided mappings.
AutoGen dependency
TypeScript SDK 0.14.0 hardens file uploads and tool execution
TypeScript SDK@composio/core 0.14.0 closes file-upload and telemetry exposure paths, prevents duplicate tool side effects after retries, and aligns trigger creation with backend connection resolution.SDK versions
File and telemetry security
- URL file uploads and automatic uploads during tool execution reject private, loopback, link-local, carrier-grade NAT, and reserved addresses. Redirects are checked at every hop, and blocked requests raise
ComposioBlockedInternalUrlError. - Error telemetry redacts URL query strings, authorization credentials, and secret-like key-value pairs before transport.
- The package root exports
assertSafeFileUploadPath,isBlockedSensitiveFileUploadPath, andBUILTIN_FILE_UPLOAD_PATH_DENY_SEGMENTSso downstream packages can apply the same sensitive-file denylist.
Tool execution reliability
tools.execute()andtools.proxyExecute()no longer retry non-idempotent writes, preventing a timeout from repeating side effects such as sending the same email twice.OpenAIProvider.handleToolCalls()executes every tool call from the first assistant choice and returns one result for eachtool_call_idin deterministic order.- Provider tool schemas normalize duplicate JSON Schema
requiredentries before they are emitted.
Trigger and toolkit behavior
triggers.create() now sends user_id directly to the backend when connectedAccountId is omitted. This removes the extra connected-account lookup and lets the backend select the first active connection for the user and toolkit.Toolkit version pins are also case-insensitive in configuration objects and environment variables, so casing differences no longer fall back silently to latest.Python SDK 0.17.0 makes sessions first-class
Python SDKcomposio 0.17.0 moves Tool Router onto a sessions-first API. It also adds webhook helpers and makes the current shared-connection ACL API easier to discover.SDK versions
Sessions and MCP
composio.sessions.create(...) is now the canonical sessions entry point. composio.create(...) and composio.use(...) remain supported shortcuts, while composio.tool_router is deprecated as an alias for the same object.Sessions return native tools by default. Set mcp=True when a typed MCP session is required. The runtime object is unchanged, but the explicit option makes the MCP dependency visible in application code.New APIs and behavior
triggers.parse()parses an incoming webhook request and can verify its signature. Passing an emptyverify_secretnow raises instead of silently skipping verification.triggers.set_webhook_subscription()creates or updates the project webhook subscription.connected_accounts.update_acl()is the primary shared-connection ACL patch helper.experimental.update_acl()remains as a deprecated alias.- Prefer
sandboxfor session code-execution configuration.workbenchremains an accepted alias.
TypeScript SDK 0.13.0 adds sessions and 0.13.1 adds deletion
TypeScript SDK@composio/core 0.13.0 makes the sessions API the primary way to work with Tool Router. Version 0.13.1 completes the lifecycle with session deletion.SDK versions
Sessions are first-class
Usecomposio.sessions.create() as the canonical entry point. composio.create() remains an alias. The shared-connection ACL helper also graduates to connectedAccounts.updateAcl(), while experimental.updateAcl() remains as a compatibility alias.MCP is now opt-in at the type level. Sessions return native tools by default. Create a session with { mcp: true } before reading session.mcp in TypeScript.Other session and trigger updates
- Session responses expose the resolved workbench configuration. Prefer
sandboxfor code-execution configuration;workbenchremains an accepted alias. triggers.parse()parses incoming webhook requests and can verify their signatures.triggers.setWebhookSubscription()creates or updates a project webhook subscription.composio.sessions.delete(sessionId)andsession.delete()remove a Tool Router session in0.13.1.
TypeScript SDK 0.12.0 and Python SDK 0.16.0
This release improves failure handling on both SDKs. TypeScript callers can cancel a request rather than waiting for a slow network operation. Python fixes file handling, request timeouts, retry safety, and schema compatibility that could otherwise produce incorrect tool calls.SDK versions
TypeScript: request cancellation and ESM-only packages
Public TypeScript SDK methods accept a trailing{ signal?: AbortSignal } request-options argument. Caller-initiated aborts are normalized to ComposioRequestCancelledError, including custom tools that cooperatively use SessionContext.signal.Before:uuid response field was also removed. Use the canonical id field instead.TypeScript improvements
authConfigs.list()addssearchandshowDisabledfilters.- Tool schema handling preserves and resolves internal
$defsand$refvalues for automatic file upload and download. - Custom tools correctly convert both Zod 3 and Zod 4 schemas to JSON Schema.
- The Anthropic provider sanitizes unsupported input-schema property names and restores the original tool arguments before execution.
Python fixes
- File fields hidden behind
$refor$defsare resolved before automatic upload and download handling. tools.execute()andtools.proxy()no longer retry non-idempotent writes, preventing duplicate side effects after timeouts, 429s, or 5xx responses.- Session file transfers and presigned S3 requests now use bounded connect and read timeouts, surfacing typed file errors rather than hanging.
- Provider tool schemas safely alias Python-invalid parameter names, preserve the original names for execution, and avoid mutating OpenAI Agents source schemas.
TypeScript SDK 0.11.0 moves custom tools to Tool Router
TypeScript SDK@composio/core 0.11.0 removes the old in-memory custom-tool registry. Custom tools now have one home: Tool Router sessions.SDK versions
Breaking change
Before:experimental_createToolkit(...) when several local tools belong together. The experimental_* names are intentional: this API is still evolving.Improvements and fixes
triggers.create()now forwardsuserId, enabling trigger 2FA ownership checks.- Telemetry sends no longer delay SDK results or rethrown errors.
- Automatic file handling now selects the correct branch for schemas that accept either one file or a list of files.
- Providers normalize model-produced JSON-string tool arguments and raise
ComposioInvalidToolArgumentsErrorfor invalid values instead of leaking raw parser errors. - MCP-backed toolkits with empty or missing output schemas no longer fail validation. Mastra also tolerates unresolved backend
$refvalues without making the whole tool list unusable.
Python SDK 0.15.0 supports trigger 2FA ownership checks
Python SDKcomposio 0.15.0 forwards user_id from triggers.create() to the trigger upsert request. This lets projects with trigger 2FA verify that the connected account belongs to the caller.SDK versions
user_id to triggers.create() when the trigger should be associated with a specific user.PostHog connections: set your data region (US or EU) per connection
The PostHog region (us or eu) now lives on the connection instead of the auth config. Region is genuinely per-connection — different users can sit in different PostHog regions — so fixing it at the auth config forced everyone through one region. Each connection now carries its own.You don’t need to do anything. We migrated every existing connection with no re-auth: connections on the default (us) stay on us, and any that used another region such as eu keep that value.Going forward
- Set
us(US Cloud) oreu(EU Cloud) on the connection. The host is built as<region>.posthog.com, so a full URL won’t work and self-hosted PostHog isn’t supported. - Link flow: the Region field appears when the user connects, prefilled with your default and editable.
- Initiate flow: you set the region, and the end user never sees it.
Setting a default on your auth config
An auth config’s region default lives in itsshared_credentials. If you were on the default (us), nothing was written there. To pin a region explicitly, set shared_credentials when you create an auth config, or patch an existing one.See the PostHog toolkit docs for the current connection fields.Python SDK 0.14.0 removes the legacy custom-tool registry
Python SDKcomposio 0.14.0 removes the legacy composio.tools.custom_tool registry. It was an older, separate custom-tool path that duplicated the Tool Router model and made it unclear which execution surface a tool belonged to.SDK versions
Breaking change
The current custom-tool APIs support inline execution and Tool Router preload, attach, and reuse flows. They are the only custom-tool path supported by the SDK.Migration
- Replace
@composio.tools.custom_toolwith@composio.experimental.tool. - Change the tool signature from a request object plus execution callback to
input, ctx. - Attach the tool when creating the session through
experimental.custom_tools.
extends_toolkit on the decorator and use ctx.proxy_execute(...) from the function body.Security, API, and platform updates
A summary of recent security, API, and platform changes you may need to act on. Most won’t apply to you, so skim for the ones that do. We are continuing to ship more.Legacy MCP Config routes
- MCP requests now require an API key or
Authorization: Bearertoken. We recommend moving tocomposio.create
API Keys
- IP whitelisting, choose which ip address can work from your api keys.
- Scoped API Key are slowly being rolled out with first preset for
proxyExecute. You will be able to control what actions your api keys can take.
Proxy Execute
- Proxy Execute is disabled on
v3api, please usev3.1or update your sdks. - Proxy Execute is now an opt-in capability on an API key, it is a superset of regular capabilities + proxy execute.
- Proxy Execute requests have a 250MB payload cap.
Connections
- Connected-account tokens are redacted in API responses, for both Composio-managed and custom auth configs. Please use Proxy Execute instead. If you need this for some special case please reach out to support.
- Reiterating: Composio-managed OAuth connections are moving from
initiatetolink. The cutover for remaining organizations is July 3, 2026.
Workbench
- Code execution through the remote workbench (
COMPOSIO_REMOTE_WORKBENCH,COMPOSIO_REMOTE_BASH_TOOL) now runs only inside a Composio session. If your code execution stopped working, run it within a Composio session.
Webhooks
- Webhook URLs must be publicly reachable; internal and loopback targets are now rejected.
- Deliveries are now signed (verify the
webhook-signatureheader), and there is a newcomposio.trigger.disabledevent. Manage subscriptions with the Webhook Subscriptions API.
Rate limits
- Per-IP rate limits now apply; requests that exceed them receive
429responses.
Endpoints
- The legacy v1 and v2 endpoints, deprecated last year, have now been removed. Any calls to
/v1orv2endpoints now return410, please use the class ofv3andv3.1endpoints, if you need a guide to migration you can use this
Python SDK 0.13.1 adds experimental shared connections
Python SDKcomposio 0.13.1 adds experimental shared connected accounts. A shared connection can be pinned in a Tool Router session and used by another user_id only when its per-user ACL permits it.SDK versions
Shared connections
Create a shared connection withconnected_accounts.link(..., experimental={...}), update its ACL with experimental.update_acl(...), and use the same experimental shape from session.authorize(...). connected_accounts.list() also accepts the PRIVATE, SHARED, and ALL account-type filters.initiate() deprecation warnings for custom and non-OAuth auth configs, preserves null-only anyOf schema branches, and adds typed errors for invalid shared-connection operations.New Endpoint: Revoke OAuth 2.0 Tokens for a Connected Account
You can now programmatically revoke a connected account’s OAuth 2.0 tokens at the upstream provider, giving you explicit control over when credentials are killed at the third-party — instead of relying on deletion or natural token expiry.The Endpoint
REVOKED and the response reports which token subjects were killed at the provider on this call.Example request:200 OK):revoked_tokens array lists the subjects revoked at the provider during this call. An empty array means the connection was already in a revoked state and no upstream dispatch was issued.Status Codes
Revoke Is Not Automatic on Delete
Deleting a connected account or a project does not revoke tokens at the upstream provider — the credentials are removed from Composio but may remain live at the third-party until they expire naturally. If you need credentials killed at the provider, follow revoke-then-delete semantics: callPOST /revoke first, then issue the delete.Revoke Is Best-Effort
Some providers do not expose a programmatic way to revoke one or both token subjects (for example, an access token but no refresh-token revoke route, or no revoke endpoint at all). In those cases, Composio revokes whatever the provider supports and therevoked_tokens array reflects exactly what was killed. Always read revoked_tokens to confirm which subjects were affected — do not assume both access_token and refresh_token were revoked on every call.Externally Revoked Tokens
If a user revokes the connection directly with the provider (for example, removing the app from their account on the provider’s website), the upstream revoke call from this endpoint may return an error. Handle this case by treating the connection as already revoked on your side.Session reuse, update, and connected accounts as arrays
Session reuse with composio.use()
composio.create() now returns a new session ID on every call, even for identical configs, for better isolation and observability. For multi-turn conversations, store the session ID and reuse it with composio.use():- Python
- TypeScript
Update session config with session.update()
Modify a session’s toolkits, auth configs, connected accounts, and other settings without creating a new session. Only the fields you pass are changed:- Python
- TypeScript
connectedAccounts accepts arrays
connectedAccounts (TypeScript) and connected_accounts (Python) now accept an array of connected account IDs per toolkit. A single string is still accepted for backwards compatibility and is automatically coerced to an array.- Python
- TypeScript
SDK versions
Sessions add preloaded tools and direct tools preset
Sessions now support preloading frequently used tools intosession.tools() and the session MCP tool list, so agents can call them without searching each time. This works for Composio-managed tools, while SDK custom tools can be exposed directly from session.tools() with preload: true.Keep the preloaded set focused, generally fewer than 20 tools, to avoid context bloat.SDK versions
- Python
- TypeScript
Direct tools preset
Specialized agents with a narrow tool set can use the direct tools preset to load every tool allowed by session filters into the session’s tool list and disable session meta tools by default.- Python
- TypeScript
- Python
- TypeScript
SDKs: link() matches initiate() for the multi-connection guard
composio.connectedAccounts.link() (TypeScript) and composio.connected_accounts.link() (Python) now match the multi-connection guard that initiate() already had. With Composio-managed redirectable-OAuth callers being migrated off POST /api/v3/connected_accounts onto POST /api/v3/connected_accounts/link, the guard moves with them — so the migration doesn’t quietly drop the duplicate-connection check.SDK versions (patch releases)
Migration
Most callers don’t need to do anything —link() raised an unrelated error or succeeded by accident in the duplicate-connection case before, and now raises a typed error you can handle. Two scenarios that need attention:1. You intentionally create multiple connections per (user, auth_config) — for example, two Gmail accounts for the same user. Opt in:- Python
- TypeScript
multiAccount / multi_account config so the agent can disambiguate at execution time. See Managing multiple connected accounts for the session shape.2. You’re migrating from initiate() to link() as part of the Composio-managed OAuth migration. Pass allow_multiple / allowMultiple through unchanged — same flag name, same default (False), same exception (ComposioMultipleConnectedAccountsError).Why
The migration changelog moves callers offconnected_accounts/create onto /link. initiate() had allow_multiple and the duplicate-connection check; link() didn’t. Without this fix, every customer who migrates would silently lose the guard and start creating duplicate ACTIVE connections on auth configs that were never meant to hold more than one. This release closes that gap.SDKs add sandbox compute tier for Tool Router workbench
The Composio SDKs now let you pick the compute tier of the sandbox when creating a Tool Router session. Heavier code execution and larger in-memory data benefit from a bigger sandbox.standard server-side when omitted, so existing code keeps working unchanged.SDK versions (patch releases)
Usage
TypeScript (camelCase on the SDK surface):SandboxSize literal type and SandboxSizeSchema zod enum are exported from @composio/core.Python (snake_case throughout):SandboxSize literal alias is available at composio.core.models.tool_router.SandboxSize.Updating an existing session
Callingsession.update() (or the equivalent PATCH /api/v3/tool_router/sessions/{id}) with a different sandbox_size recreates the sandbox on next access. The sandbox’s in-memory filesystem state is lost, but the persistent /mnt/files/ mount survives the restart.See Configuring Sessions → Sandbox compute tier for the full reference.Webhook Triggers V2
Webhook Triggers V2 introduces a first-classwebhook_endpoints resource with a dedicated ingress URL per OAuth app. V2 is opt-in and scoped to new trigger slugs — existing V1 triggers, URLs, and payload formats are unchanged.Summary
What’s in V2
Dedicated endpoint per OAuth app. Eachwebhook_endpoint is keyed by (toolkit_slug, project_id, client_id) and exposes its own URL containing a random we_* identifier:/handle URL per toolkit. Events arriving on a V2 URL are fanned out only to trigger instances on that endpoint’s project.Signature verification at ingress. Composio cryptographically verifies every V2 request against the signing secret stored on the endpoint, using HMAC-SHA256, Ed25519, or shared-token matching depending on the toolkit. Unsigned or tampered payloads are rejected, so third parties cannot spoof events onto your triggers. For providers that sign a request timestamp (e.g. Slack), replay protection additionally rejects requests whose timestamp falls outside the allowed skew window.Per-user authorization for app-level events. On toolkits with per-user visibility — Slack being the first — V2 uses an app-level token (for Slack, an xapp-… token with authorizations:read) to resolve which connected users are authorized for a given event, so only those users’ triggers fire. This underpins a new class of triggers for private channels, direct messages, and other per-recipient events, each routed only to the user the event was intended for.Automatic handshakes and cleanup. Composio responds to provider verification challenges — Slack url_verification, Asana X-Hook-Secret, Outlook validation tokens, and so on — so callback URLs verify without any custom code. User-level webhooks are also deregistered on the provider side when the trigger is deleted.API reference
All endpoints require a project API key (x-api-key).Migration walkthrough (Slack)
Slack is the first toolkit on V2. The same flow applies to every toolkit added later.1. Discover required fields
2. Create the endpoint
id (used as ENDPOINT_ID in the next steps) and webhook_url (the URL you’ll paste into your Slack app dashboard in step 5). The call is idempotent — calling it again with the same toolkit_slug and client_id returns the existing endpoint.3. Store the signing secret
4. Add an app-level token for private-scope events
The app-level token is what lets Composio resolve per-user authorization for Slack’s private-scope events.SLACK_DIRECT_MESSAGE_RECEIVEDalways requires it.SLACK_CHANNEL_MESSAGE_RECEIVEDrequires it for events from private channels and multi-person DMs; public-channel messages are delivered without it.
authorizations:read.5. Point your Slack app at the V2 URL
Set Event Subscriptions → Request URL in your Slack app to thewebhook_url returned in step 2. Composio verifies the endpoint with Slack automatically — no extra action needed on your side.6. Create V2 trigger instances
Three new Slack triggers go live on V2 today, with more to follow on V2 — both for Slack and for other toolkits. The table below maps your existing V1 slugs to the new V2 equivalents:Heads up: OAuth apps are project-scoped on V2
The provider dashboard accepts only one callback URL per OAuth app, and each V2 URL resolves to exactly one project — so a single OAuth app cannot feed multiple projects on V2.The signing secret also lives on the endpoint, so the reverse holds too: two different OAuth apps cannot share one V2 endpoint — Composio only verifies signatures against the secret stored on that endpoint, so requests signed by a different OAuth app would be rejected.In return, every project graduates to a first-class webhook tenant on V2 — with its own:- Ingress rate-limit and backpressure budget
- Clean fan-out — events reach only that project’s trigger instances
- Signing secret and app-level token, scoped to this project alone
- Per-project metering and billing
Backward compatibility
Everything you have today keeps working — same URLs, same trigger slugs, same payload shapes, no data migration.- The V1 ingress URL (
/api/v3/trigger_instances/{toolkit}/{project_id}/handle) is not deprecated. - Every existing trigger slug —
SLACK_RECEIVE_*,SLACKBOT_*, and the equivalent legacy slugs on other toolkits — continues to route through V1.
- You want to use one of the new V2 trigger slugs (e.g.
SLACK_CHANNEL_MESSAGE_RECEIVED,SLACK_DIRECT_MESSAGE_RECEIVED). A V2 endpoint is required at setup; without one, the upsert returns400. - You want to move an OAuth app that’s currently shared across multiple projects or organizations onto V2. Pick the project that should own it on V2 and set up an endpoint there, or register separate OAuth apps per project (see Heads up: OAuth apps are project-scoped on V2).
SDKs remove legacy automatic file handling config
The Composio SDKs no longer accept the legacy flags that previously controlled automatic file upload and download during tool execution. Automatic handling offile_uploadable fields stays off by default; you opt in with the explicit dangerously* option only.SDK versions (minor releases)
@composio/* npm packages that depend on core are published as patch bumps in the same release train (via the changesets updateInternalDependencies: "patch" setting) so they pick up the updated ComposioConfig surface — they have no public-API changes of their own.Migration
Earlier SDK versions treated automatic file upload/download forfile_uploadable tool fields as on by default (TypeScript: autoUploadDownloadFiles defaulted to true when unset; Python followed the same idea for auto_upload_download_files in prior releases). That default is now off. If you still want that behavior, you must explicitly set dangerouslyAllowAutoUploadDownloadFiles: true (TypeScript) or dangerously_allow_auto_upload_download_files=True (Python).TypeScript — before (legacy):true to match either legacy pattern above):dangerouslyAllowAutoUploadDownloadFiles or set it to false.Python — before (legacy):True to match either legacy pattern above):ToolRouterSession directly (unusual), the keyword argument is now dangerously_allow_auto_upload_download_files instead of auto_upload_download_files.Local paths must live inside an allowlisted directory
Even withdangerouslyAllowAutoUploadDownloadFiles enabled, the SDK will only auto-upload local file paths that resolve inside an allowlisted directory. Paths outside the allowlist are rejected with ComposioFileUploadPathNotAllowed (TypeScript) / FileUploadPathNotAllowed (Python) before any file is read or sent.This is a behavior change. Earlier SDK versions had no allowlist: any local path the legacy default-on flag saw was uploaded.Default allowlist:http://… / https://…) and JavaScript File objects are not subject to the allowlist — only local string paths are.TypeScript:composio.files.upload(...). That call bypasses the allowlist by design (the caller is expected to control the path), and the returned { name, mimetype, s3key } descriptor can be passed straight into tools.execute:dangerously_allow_auto_upload_download_files=True and configure file_upload_dirs to cover the directories your code reads from.What else changed
- TypeScript:
resolveAutoUploadDownloadFilesEnabledonly considersdangerouslyAllowAutoUploadDownloadFiles; the old deprecation warning for the legacy property is removed. - Python: the small
composio.utils.auto_upload_downloadhelper that merged legacy + new flags is removed;ToolsandToolRoutertake only the explicit opt-in boolean.
Link Auth Migration for Composio-Managed OAuth Connections
POST /api/v3/connected_accounts is being retired for Composio-managed OAuth connections. New organizations begin migrating on Friday, May 8, 2026, and all remaining organizations follow on Friday, July 3, 2026. Once migrated, affected requests receive 400 BadRequest with a message pointing at the replacement endpoint.This does not affect custom auth configs (your own OAuth app) or non-OAuth schemes (API key, bearer token, basic auth, etc.) — those continue to work on POST /api/v3/connected_accounts unchanged. Only the specific combination of Composio-managed auth config + redirectable OAuth scheme (OAuth1, OAuth2, DCR_OAUTH) is moving.What’s Changing
Why
When a connection is initiated through a default (Composio-managed) auth config, a Composio-owned OAuth application is acting on behalf of your integration. We want the end user to explicitly understand and acknowledge, at the moment of connection, that they are granting a third-party application access to their account on the external service. That acknowledgement is enforced by the/link flow, which routes the user through a consent screen before the connection is created. The legacy POST /api/v3/connected_accounts path allowed that step to be bypassed when credentials were passed in directly, which this change closes.Custom auth configs are unaffected because they are backed by your own OAuth application — the consent screen is served by your app, so you already own that experience. This change is scoped specifically to default auth configs on redirectable schemes, where the third-party relationship is with Composio rather than with the developer.Migration
Before — legacy create (will be rejected for Composio-managed OAuth):redirect_url (valid for 10 minutes) that the end user opens to authorize the integration, plus a connected_account_id you can use to poll for status or associate with your own records.Error Response (after rollout)
Requests that hit the retired combination receive:What to Do
- If you use Composio-managed OAuth auth configs (OAuth1, OAuth2, or DCR_OAUTH) via
POST /api/v3/connected_accounts: switch toPOST /api/v3/connected_accounts/linkbefore your org’s cutover — Friday, May 8, 2026 for organizations created on or after that date, Friday, July 3, 2026 for all others. - If you already use
/link: no action required. - If you use custom OAuth apps (your own
client_id/client_secret) or non-OAuth auth (API key, bearer, etc.): no action required — the legacy endpoint continues to serve those cases.
Proxy execute now enforces same-domain endpoints
To prevent a connection’sAuthorization header from being forwarded to an unintended host, the proxy execute endpoint (POST /api/v3/tools/execute/proxy) now requires that the outbound endpoint URL share the same scheme and registrable domain (eTLD+1) as the connection’s resolved base_url.Cross-subdomain requests on the same registrable domain continue to work — for example, a Gmail connection with base https://gmail.googleapis.com can still call https://www.googleapis.com/.... Relative endpoints (/users/me/messages) are resolved against the connection’s base_url as before and are unaffected.Migration
If you currently pass an absolute URL that points at a different domain than your connection’sbase_url, switch to a relative endpoint (resolved against base_url) or an absolute URL under the same registrable domain.Before — absolute URL on a different domain (will be rejected):base_url:What changed
- Absolute
endpointURLs on a different registrable domain than the connection’sbase_urlare rejected with HTTP400 OriginMismatch. The upstream request is never made. - Proxy calls that provide neither
connected_account_idnorcustom_connection_datanow return HTTP400 MissingAuthContextinstead of being forwarded without auth.
Examples
Assume a connected account whose toolkitbase_url is https://api.linear.app.Allowed — relative endpoint:What to do
- If you call proxy execute with absolute URLs, make sure the host matches (or is a subdomain of) the connection’s
base_url. - Prefer relative endpoints (
/path) — they are resolved againstbase_urland are not affected by this change. - If your integration legitimately needs to span multiple registrable domains for the same connection, reach out to us so we can add the additional host to the toolkit allowlist.
SDK file upload hardening: sensitive path blocking and upload hooks
The Composio SDKs add defense-in-depth for automatic file uploads (when a tool input is markedfile_uploadable and the SDK reads a local path and sends the file to Composio storage). The goal is to reduce the risk of agent or app code accidentally exfiltrating secrets, SSH keys, or project env files that sit under well-known paths on disk.URLs and File objects are not subject to the path-based denylist in the same way as string paths; the checks apply to resolved local filesystem paths used for auto-upload and the programmatic upload helpers that accept paths.SDK versions
What changed
- Default sensitive path protection — Before reading and uploading, the SDK checks the resolved local path against a built-in list of path segments (for example
.ssh,.aws,.claude,.kube) and file-name patterns (for example.env, default SSH private key names,credentials). If the path matches, the upload is refused unless you change configuration. - Extra denylist segments — You can add path component names to merge with the built-in list (for example a proprietary secrets directory name).
beforeFileUpload/before_file_uploadhook — Optional hook for each file upload: return a different path, returnfalseto abort, or throw. TypeScript: passbeforeFileUploadon the third argument totools.execute. Python: use@before_file_uploadin themodifierslist (same as other Python modifiers), not a separate keyword. Use this to enforce app-specific policies, audit logging, or copy-on-write to a safe temp file before upload. See Before file upload (Python).- New errors —
ComposioSensitiveFilePathBlockedError/SensitiveFilePathBlockedErrorwhen a path is blocked, andComposioFileUploadAbortedError/FileUploadAbortedErrorwhen the hook returnsfalseor a hook throws in an aborting way. - Python: modifier order —
substitute_file_uploadsruns beforebefore_executemodifiers, matching TypeScript behavior (including Tool Routerexecute_meta).
Examples
Configure the client (defaults + extra denylist segments)
Keep the built-in blocklist enabled and add path component names (anywhere in the resolved path) that your app treats as secret:- TypeScript
- Python
Run a hook before each automatic file read
Return a new path, returnfalse / False to abort, or throw. TypeScript passes beforeFileUpload in the third argument to tools.execute. In Python, use @before_file_upload in modifiers:- TypeScript
- Python
Opting out
SetsensitiveFileUploadProtection: false (TypeScript) or sensitive_file_upload_protection=False (Python) only if you have a clear reason and accept the security tradeoff. Prefer copying files to a non-sensitive path or using the hook to gate uploads.- TypeScript
- Python
Where to read more
- Executing tools: automatic file handling and security options — configuration and code patterns.
- TypeScript
Composioclient — related constructor options in the reference. - TypeScript SDK (repository):
ts/docs/advanced/auto-upload-download.md— extended guide with error types and edge cases.
Webhook Event for Auto-Disabled Triggers
composio.trigger.disabled is a new V3 webhook event that fires when Composio disables one of your triggers without a request from you — expired credentials, a failed webhook-subscription refresh, or unhealthy polling. It’s opt-in: add it to a webhook subscription’s enabled_events to receive it. Existing subscriptions for composio.trigger.message and composio.connected_account.expired are unaffected.When it fires
The event is emitted only for platform-initiated disables.data.disabled_reason names the cause:PATCH /api/v3/trigger_instances/manage/{id} nor by deactivating the connected account via PATCH /api/v3/connected_accounts/{id}/status.Subscribe
Addcomposio.trigger.disabled to your subscription’s enabled_events — via the dashboard webhook settings or the Webhook Subscriptions API:Payload
connection_expired.Credential Redaction for Composio-Managed Auth Configs and Connections
Two related security changes are rolling out together:- Connections on Composio-managed auth configs now always redact
access_token,refresh_token, and theAuthorizationheader inconnected-accountsresponses — independent of your project’smask_secret_keys_in_connected_accountflag. - Auth-config GET responses now redact (for Composio-managed) or mask (for customer-owned) every sensitive credential field.
mask_secret_keys_in_connected_account. That project flag only applies to runtime connected-account credentials (access tokens, refresh tokens, and the like). Auth-config credentials are developer-owned static fields — client_id, client_secret, developer_token, etc. — and are always redacted or masked regardless of the mask_secret_keys_in_connected_account project flag.Most integrations need no changes.- Tool execution through the SDK, Tool Router, and MCP is unchanged. Composio uses the unredacted values server-side.
- Connections on customer-owned auth configs continue to follow your project’s
mask_secret_keys_in_connected_accountsetting for runtime tokens.
What is a Composio-managed auth config?
When you connect a user through a toolkit’s default integration — for example, Gmail or Slack without registering your own OAuth application — Composio uses an OAuth application it owns and shares across every team on that default. Tokens the provider issues are bound to that shared Composio-owned client.You can identify a Composio-managed auth config or connection byis_composio_managed: true on the auth-config or connected-account resource.1. Connected-account tokens
Access tokens, refresh tokens, and all header and query-parameter values are now replaced with the literal string"REDACTED" for Composio-managed connections. No prefix, no suffix — nothing that reveals the underlying value.Before, with mask_secret_keys_in_connected_account: false on a Composio-managed Gmail connection:mask_secret_keys_in_connected_account setting (xxxx... truncation when enabled, raw passthrough when disabled).If you were reading Composio-managed access or refresh tokens from these responses — typically because you use Composio for OAuth and then call the provider’s APIs yourself — register your own OAuth application with the provider and create a custom auth config against those credentials. Tokens issued against an OAuth application you own belong to you and are returned in full (subject to mask_secret_keys_in_connected_account).2. Auth-config credentials
GET /api/v3/auth_configs and GET /api/v3/auth_configs/{id} no longer return sensitive credentials in a recoverable form.- Composio-managed auth configs — every credential field is redacted.
- Customer-owned auth configs — public OAuth identifiers (
client_id,consumer_key) still pass through so you can debug OAuth flows. Every other credential field is obfuscated.
client_secret or developer_token — out of these responses, you will need to keep that value alongside the code that created the auth config (typically in your own secret manager at upload time).Why this change
A single OAuth application backs every team on a Composio-managed default integration, and the tokens and client secrets bound to it are shared. If a provider throttles, restricts, or suspends that app in response to misuse of one of its credentials, the integration becomes unavailable for every team on the default at once. Redacting the values keeps them out of API responses; Composio still uses them server-side, so tool execution is unchanged.For customer-owned auth configs, masking a freshly re-readclient_secret or developer_token limits the blast radius of a compromised project API key without breaking your ability to identify which credential was uploaded.Affected endpoints
Connected accounts:GET /api/v3/connected_accounts/{id}GET /api/v3/connected_accountsPOST /api/v3/connected_accounts- Webhook payloads that include connection credentials
access_token, refresh_token, client_secret, or developer_token from Composio API responses, you will need to act. All other integrations continue to work as before.Observability APIs: tool execution logs and usage metering
Two new v3.1 observability API surfaces are live.Tool execution logs
Search, filter, and paginate individual tool execution events. Use this for debugging failures, inspecting request/response payloads, and tracing user activity.POST /api/v3.1/logs/tool_execution— list with filters, time range, and cursor pagination.GET /api/v3.1/logs/tool_execution/{id}— full detail including request payload, response body, timings, and source metadata.
x-api-key) or session cookie.See the tool execution logs guide.Usage metering
Aggregated counts of tool calls and sessions. Summary endpoints return totals; breakdown endpoints group results by tool, toolkit, user, session, or project.POST /api/v3.1/org/usage/summaryandPOST /api/v3.1/org/usage/{entity_type}— org scope (x-org-api-keyor org JWT).POST /api/v3.1/project/usage/summaryandPOST /api/v3.1/project/usage/{entity_type}— project scope (x-api-keyor cookie).
tool_calls, sessions. Time ranges are epoch milliseconds; max range 366 days.See the usage metering guide.Multi-Account Mode & Connection Aliases
This release adds two features for managing multiple accounts per toolkit.Multi-account mode
Sessions now support amultiAccount config that lets users connect and use multiple accounts for the same toolkit (e.g., work and personal Gmail) within a single session.Connection aliases
Connected accounts can now have human-readable aliases (e.g.,"work-gmail", "personal-github"). Aliases can be set during connection or updated after.Introducing API v3.1 - Latest Tool Versions by Default
We’re rolling out API v3.1 endpoints that change how tool versions are resolved. The key difference: tool-related endpoints now default to the latest toolkit version instead of the legacy pinned version (00000000_00).What Changed
In API v3 (/api/v3/tools/*), tool-related endpoints default the version parameter to 00000000_00 (the initial pinned version). This means callers must explicitly pass version: "latest" (or toolkit_versions: "latest" for GET /tools) to get the most recent tool definitions.In API v3.1 (/api/v3.1/tools/*), the default is flipped: tool-related endpoints default to the latest toolkit version. If you’re already passing version: "latest" in your requests, switching to v3.1 changes nothing for you. If you were relying on the 00000000_00 default, you’ll now get the latest version unless you explicitly pin.Affected tool endpoints (those with a version parameter):Triggers Are Unchanged
Trigger endpoints already default theversion parameter to latest in both v3 and v3.1, so there is no behavior change for triggers. If you’re using triggers, switching to v3.1 requires no changes.All Other Endpoints Are Unchanged
Every non-tool endpoint (/auth_configs, /connected_accounts, /triggers, /toolkits, etc.) behaves identically between v3 and v3.1. They are served at both /api/v3/ and /api/v3.1/ paths with the same request and response contracts.Migration Guide
If you’re using the Composio SDK: No action needed. The SDK will adopt v3.1 endpoints in an upcoming release.If you’re calling the API directly:- Replace
/api/v3/with/api/v3.1/in your tool endpoint URLs - If you depend on a specific pinned version, pass it explicitly —
version=00000000_00for most endpoints, ortoolkit_versions=00000000_00forGET /tools(see table above) - If you were already passing
version: "latest"(ortoolkit_versions: "latest"), you can drop the parameter entirely on v3.1
Bearer Token Connections & Credential Patching
Two features for teams managing their own authentication credentials.Bearer Token for OAuth Toolkits
All OAuth2 toolkits (Gmail, GitHub, Slack, Google Docs, and more) now supportBEARER_TOKEN as an auth scheme. Import your own access tokens directly without setting up an OAuth app.BEARER_TOKEN is injected as an alternative scheme alongside OAuth2, so existing OAuth connections are unaffected.How to use
- Create a custom auth config with
authScheme: "BEARER_TOKEN"for the toolkit - Create a connected account with your access token
- Pass the auth config or connection ID to
composio.create()for use with Tool Router
Credential Patching
NewPATCH /api/v3/connected_accounts/{nanoid} endpoint and SDK method — update credentials and alias on existing connections without recreating them.- Keep access tokens updated — call PATCH whenever you refresh the token on your end (e.g., after an OAuth refresh flow)
- Partial updates — omitted fields are preserved, fields set to
nullare removed - Supported schemes — BEARER_TOKEN, API_KEY, BASIC, BASIC_WITH_JWT, GOOGLE_SERVICE_ACCOUNT, SERVICE_ACCOUNT
Tool consolidation and improved enum naming
We’ve completed a major effort to make Composio tools more agent-friendly. This release consolidates overlapping tools, deprecates redundant ones, and renames enum slugs to be cleaner and more intuitive for AI agents.What’s changing?
1. Consolidated overlapping tools
Many toolkits had multiple tools that performed similar functions — sometimes originating from different API versions or slightly different wrappers around the same endpoint. We’ve unified these into single, well-defined tools. The consolidated tools retain full functionality while reducing noise for agents selecting tools.This affects 30+ toolkits. Tools that didn’t add meaningful value to agent workflows have been removed, and their functionality is covered by the remaining tools.2. Deprecated high-usage duplicates
For tools that had significant active usage, we’ve soft-deprecated them rather than removing them outright. These tools still work but will return a deprecation notice pointing to the recommended replacement. We encourage migrating to the replacement tools listed below.3. Renamed enum slugs for agent clarity
We’ve renamed 1,445 tool enum slugs across 37 toolkits to be shorter, more consistent, and easier for agents to understand. The old names often contained unnecessary filler words (A, AN, THE, FOR_THE_AUTHENTICATED_USER) or verbose patterns that made it harder for agents to match the right tool. The new names follow a consistent APP_VERB_NOUN pattern.No action required
If you are usinglatest toolkit versions or fetching tools dynamically, these changes will not break your integration. The SDK automatically resolves the correct tool names.If you are pinning tool enums by name in your code, check the tables below for any renames or deprecations that affect you.Deprecated tools
These tools still work but now point to a recommended replacement. Migrate when convenient.Gmail (1 deprecated)
Gmail (1 deprecated)
Google Calendar (2 deprecated)
Google Calendar (2 deprecated)
Google Docs (2 deprecated)
Google Docs (2 deprecated)
Google Drive (5 deprecated)
Google Drive (5 deprecated)
Google Sheets (2 deprecated)
Google Sheets (2 deprecated)
Google Tasks (2 deprecated)
Google Tasks (2 deprecated)
Outlook (3 deprecated)
Outlook (3 deprecated)
Slack (1 deprecated)
Slack (1 deprecated)
HubSpot (0 deprecated, see consolidated)
HubSpot (0 deprecated, see consolidated)
Instagram (7 deprecated)
Instagram (7 deprecated)
Notion (1 deprecated)
Notion (1 deprecated)
GitHub (2 deprecated)
GitHub (2 deprecated)
Airtable (2 deprecated)
Airtable (2 deprecated)
Attio (4 deprecated)
Attio (4 deprecated)
Jira (2 deprecated)
Jira (2 deprecated)
Linear (1 deprecated)
Linear (1 deprecated)
Microsoft Teams (3 deprecated)
Microsoft Teams (3 deprecated)
Pipedrive (2 deprecated)
Pipedrive (2 deprecated)
Reddit (1 deprecated)
Reddit (1 deprecated)
Salesforce (3 deprecated)
Salesforce (3 deprecated)
Shopify (4 deprecated)
Shopify (4 deprecated)
Stripe (2 deprecated)
Stripe (2 deprecated)
YouTube (1 deprecated)
YouTube (1 deprecated)
Gemini (1 deprecated)
Gemini (1 deprecated)
Consolidated (removed) tools
These tools have been removed because their functionality is fully covered by other existing tools. If you were using any of these, switch to the canonical tool for that operation.Google Drive (35 removed)
Google Drive (35 removed)
GOOGLEDRIVE_ADD_SHARED_DRIVE_MEMBER, GOOGLEDRIVE_COPY_FILE_V2, GOOGLEDRIVE_INSERT_COMMENT, GOOGLEDRIVE_DELETE_FILE, GOOGLEDRIVE_DELETE_PERMISSION_V2, GOOGLEDRIVE_DELETE_REPLY_V2, GOOGLEDRIVE_DELETE_TEAM_DRIVE_V2, GOOGLEDRIVE_GET_ABOUT_V2, GOOGLEDRIVE_GET_CHANGES_START_PAGE_TOKEN_V2, GOOGLEDRIVE_GET_PERMISSION_V2, GOOGLEDRIVE_GET_REVISION_V2, GOOGLEDRIVE_GET_TEAM_DRIVE_V2, GOOGLEDRIVE_INSERT_FILE, GOOGLEDRIVE_INSERT_PERMISSION, GOOGLEDRIVE_LIST_CHANGES_V2, GOOGLEDRIVE_LIST_CHILDREN_V2, GOOGLEDRIVE_LIST_DRIVE_COMMENTS, GOOGLEDRIVE_LIST_DRIVE_REPLIES, GOOGLEDRIVE_LIST_FILE_LABELS_V2, GOOGLEDRIVE_LIST_PARENTS_V2, GOOGLEDRIVE_LIST_PERMISSIONS_V2, GOOGLEDRIVE_LIST_REVISIONS_V2, GOOGLEDRIVE_LIST_TEAM_DRIVES_V2, GOOGLEDRIVE_PATCH_COMMENT, GOOGLEDRIVE_STOP_CHANNEL_V2, GOOGLEDRIVE_TOUCH_FILE_V2, GOOGLEDRIVE_TRASH_FILE_V2, GOOGLEDRIVE_UPDATE_COMMENT_V2, GOOGLEDRIVE_UPDATE_DRIVE_V2, GOOGLEDRIVE_UPDATE_PERMISSION_V2, GOOGLEDRIVE_UPDATE_REPLY_V2, GOOGLEDRIVE_UPDATE_TEAM_DRIVE_V2, GOOGLEDRIVE_UPLOAD_MEDIA_FILE, GOOGLEDRIVE_WATCH_CHANGES_V2, GOOGLEDRIVE_WATCH_FILE_V2Outlook (79 removed)
Outlook (79 removed)
OUTLOOK_CANCEL_CALENDAR_EVENT, OUTLOOK_CANCEL_EVENT, OUTLOOK_CANCEL_CALENDAR_GROUP_CALENDAR_EVENT, OUTLOOK_COPY_MAIL_FOLDER, OUTLOOK_COPY_MESSAGE_FROM_MAIL_FOLDER, OUTLOOK_CREATE_CALENDAR_EVENT_IN_CALENDAR, OUTLOOK_CREATE_CALENDAR_GROUP_CALENDAR_EVENT_ATTACHMENT, OUTLOOK_CREATE_CONTACT_FOLDER_CHILD_FOLDER, OUTLOOK_CREATE_EVENT_ATTACHMENT, OUTLOOK_CREATE_FORWARD_DRAFT, OUTLOOK_CREATE_MAIL_FOLDER_MESSAGE_RULE, OUTLOOK_CREATE_ME_CHILD_FOLDER_MESSAGE, OUTLOOK_CREATE_ME_CONTACT_FOLDERS_CONTACTS, OUTLOOK_CREATE_ME_CONTACT_FOLDERS_CONTACTS_EXTENSIONS, OUTLOOK_CREATE_ME_CONTACT_IN_CHILD_FOLDER, OUTLOOK_CREATE_ME_CONTACTS, OUTLOOK_CREATE_ME_EVENT, OUTLOOK_CREATE_ME_FORWARD_DRAFT, OUTLOOK_CREATE_ME_INFERENCE_CLASSIFICATION_OVERRIDE, OUTLOOK_CREATE_ME_MESSAGE_REPLY_ALL_DRAFT, OUTLOOK_CREATE_ME_REPLY_ALL_DRAFT, OUTLOOK_CREATE_ME_REPLY_DRAFT, OUTLOOK_DELETE_CALENDAR_EVENT_ATTACHMENT, OUTLOOK_DELETE_CALENDAR_FROM_GROUP, OUTLOOK_DELETE_CALENDAR_GROUP_CALENDAR_EVENT, OUTLOOK_DELETE_CALENDAR_PERMISSION, OUTLOOK_DELETE_CONTACT_FOLDER_CHILD_FOLDER, OUTLOOK_DELETE_CONTACT_FROM_CHILD_FOLDER_PERMANENTLY, OUTLOOK_DELETE_ME_CALENDAR_PERMISSION, OUTLOOK_DELETE_ME_CONTACT_EXTENSION, OUTLOOK_DELETE_ME_CONTACT_FOLDER_CONTACT_EXTENSION, OUTLOOK_DELETE_ME_EVENT_EXTENSION, OUTLOOK_DELETE_ME_EVENTS_ATTACHMENTS, OUTLOOK_DELETE_ME_INFERENCE_CLASSIFICATION_OVERRIDE, OUTLOOK_DELETE_ME_MAIL_FOLDER_CHILD_FOLDER, OUTLOOK_DELETE_ME_MAIL_FOLDER_MESSAGE_RULE, OUTLOOK_DELETE_ME_MAIL_FOLDERS, OUTLOOK_DELETE_ME_MAIL_FOLDERS_CHILD_FOLDERS_MESSAGES_EXTENSIONS, OUTLOOK_DELETE_ME_MAIL_FOLDERS_MESSAGES_ATTACHMENTS, OUTLOOK_DELETE_PRIMARY_CALENDAR_PERMISSION, OUTLOOK_DISMISS_CALENDAR_EVENT_REMINDER, OUTLOOK_DISMISS_EVENT_REMINDER_FROM_GROUP, OUTLOOK_GET_CALENDAR_GROUP_SCHEDULE, OUTLOOK_GET_CALENDAR_PERMISSION, OUTLOOK_GET_CALENDAR_PERMISSION_FROM_CALENDAR, OUTLOOK_GET_CONTACT_FOLDERS, OUTLOOK_GET_MAIL_FOLDER_MESSAGE_RULE, OUTLOOK_GET_ME_CONTACT_FOLDERS_CHILD_FOLDER, OUTLOOK_GET_ME_CONTACTS, OUTLOOK_GET_ME_CONTACTS_EXTENSIONS, OUTLOOK_GET_ME_EVENT_ATTACHMENT, OUTLOOK_GET_ME_EVENT_CALENDAR, OUTLOOK_GET_ME_MAIL_FOLDERS_MESSAGES_EXTENSIONS, OUTLOOK_GET_ME_OUTLOOK, OUTLOOK_GET_MESSAGE_EXTENSION, OUTLOOK_GET_SUPPORTED_TIME_ZONES, OUTLOOK_LIST_CALENDAR_EVENT_ATTACHMENTS, OUTLOOK_LIST_CALENDAR_GROUP_CALENDAR_EVENTS, OUTLOOK_LIST_CALENDAR_GROUP_EVENT_ATTACHMENTS, OUTLOOK_LIST_CHILD_FOLDER_CONTACTS, OUTLOOK_LIST_CONTACTS, OUTLOOK_LIST_ME_CALENDAR_PERMISSIONS, OUTLOOK_MOVE_ME_MAIL_FOLDER, OUTLOOK_SNOOZE_CALENDAR_EVENT_REMINDER, OUTLOOK_SNOOZE_CALENDAR_GROUP_EVENT_REMINDER, OUTLOOK_UPDATE_CALENDAR, OUTLOOK_UPDATE_CALENDAR_GROUPS_CALENDARS, OUTLOOK_UPDATE_CALENDAR_GROUPS_CALENDARS_EVENTS, OUTLOOK_UPDATE_CONTACT_FOLDER, OUTLOOK_UPDATE_CONTACT_FOLDER_CHILD_FOLDER, OUTLOOK_UPDATE_ME_CALENDAR, and othersStripe (75+ removed)
Stripe (75+ removed)
STRIPE_CREATE_BILLING_CREDIT_GRANT, STRIPE_CREATE_CARD, STRIPE_CREATE_SETUP_INTENT, STRIPE_DELETE_COUPON, STRIPE_DELETE_CUSTOMER_DISCOUNT, STRIPE_DELETE_CUSTOMER_TAX_ID, STRIPE_DELETE_INVOICEITEM, STRIPE_DELETE_PLAN, STRIPE_DELETE_SUBSCRIPTION_ITEM, STRIPE_DELETE_TAX_ID, STRIPE_DELETE_TERMINAL_LOCATION, STRIPE_DOWNLOAD_QUOTE_PDF, STRIPE_FIND_APPS_SECRET, STRIPE_GET_BALANCE_HISTORY_2, and many more get_v1_* and post_v1_* duplicates.Shopify (56 removed)
Shopify (56 removed)
SHOPIFY_ADD_PRODUCT_TO_COLLECTION, SHOPIFY_CANCEL_FULFILLMENT_ORDER, SHOPIFY_CANCEL_ORDER, SHOPIFY_CLOSE_ORDER, SHOPIFY_COUNT_LOCATION, SHOPIFY_COUNT_WEBHOOK, SHOPIFY_CREATE_A_METAFIELD_2, SHOPIFY_CREATE_A_NEW_WEBHOOK, SHOPIFY_CREATE_COUNTRY, SHOPIFY_CREATE_FULFILLMENT_ORDER, SHOPIFY_CREATES_A_FULFILLMENT_EVENT, SHOPIFY_CREATES_A_GIFT_CARD, SHOPIFY_CREATES_A_PRICE_RULE, SHOPIFY_CREATES_A_REDIRECT, SHOPIFY_CREATE_REFUND, SHOPIFY_DEL_FULFILLMENT_EVENT, SHOPIFY_DEL_METAFIELD, SHOPIFY_DEL_SCRIPTTAG, SHOPIFY_DEL_WEBHOOK, SHOPIFY_DELETE_AN_ARTICLE, SHOPIFY_DELETES_A_PRODUCT, SHOPIFY_DELETE_REDIRECT, SHOPIFY_DISABLE_GIFT_CARD, SHOPIFY_GET_CUSTOM_COLLECTION, SHOPIFY_GET_CUSTOMER, SHOPIFY_GET_GIFT_CARD, SHOPIFY_GET_GIFT_CARDS, SHOPIFY_GET_GIFT_CARDS_COUNT, SHOPIFY_SEARCH_CUSTOMERS, SHOPIFY_SEARCHES_FOR_GIFT_CARDS, and others.Pipedrive (44 removed)
Pipedrive (44 removed)
PIPEDRIVE_ADD_A_COMMENT_TO_A_NOTE, PIPEDRIVE_ADD_A_FOLLOWER_TO_A_PERSON, PIPEDRIVE_ADD_A_FOLLOWER_TO_A_PRODUCT, PIPEDRIVE_ADD_A_FOLLOWER_TO_AN_ORGANIZATION, PIPEDRIVE_ADD_A_PRODUCT_TO_A_DEAL, PIPEDRIVE_DELETE_A_DEAL, PIPEDRIVE_DELETE_A_DEAL_FIELD, PIPEDRIVE_DELETE_A_FILE, PIPEDRIVE_DELETE_A_FILTER, PIPEDRIVE_GET_DETAILS_OF_A_DEAL, PIPEDRIVE_GET_ONE_DEAL_FIELD, PIPEDRIVE_PIPEDRIVE_ADD_DEAL_PARTICIPANT, PIPEDRIVE_PIPEDRIVE_DEALS_DELETE_DEAL, PIPEDRIVE_PIPEDRIVE_DEALS_DELETE_DEAL_V2, PIPEDRIVE_PIPEDRIVE_DELETE_WEBHOOK, PIPEDRIVE_PIPEDRIVE_GET_DEAL_BY_ID, PIPEDRIVE_PIPEDRIVE_GET_FILE, PIPEDRIVE_PIPEDRIVE_GET_FILTER, PIPEDRIVE_PIPEDRIVE_GET_LEAD, PIPEDRIVE_PIPEDRIVE_GET_NOTE, PIPEDRIVE_PIPEDRIVE_GET_PIPELINE, PIPEDRIVE_PIPEDRIVE_GET_PRODUCT, PIPEDRIVE_PIPEDRIVE_GET_STAGE, and others.Microsoft Teams (19 removed)
Microsoft Teams (19 removed)
MICROSOFT_TEAMS_ARCHIVE_GROUP_TEAM, MICROSOFT_TEAMS_CLONE_GROUP_TEAM, MICROSOFT_TEAMS_DELETE_ONLINE_MEETING, MICROSOFT_TEAMS_GET_CHAT, MICROSOFT_TEAMS_GET_CHAT_LAST_MESSAGE_PREVIEW, MICROSOFT_TEAMS_GET_CHAT_MEMBER, MICROSOFT_TEAMS_GET_MY_PRESENCE, MICROSOFT_TEAMS_GET_PRESENCE, MICROSOFT_TEAMS_GET_TEAM_FROM_GROUP, MICROSOFT_TEAMS_GET_TEAMS_APP_DEFINITION, MICROSOFT_TEAMS_LIST_CHANNELS, MICROSOFT_TEAMS_LIST_CHAT_MEMBERS, MICROSOFT_TEAMS_LIST_MESSAGE_REPLIES, MICROSOFT_TEAMS_SET_SCHEDULE, MICROSOFT_TEAMS_UNARCHIVE_GROUP_TEAM, MICROSOFT_TEAMS_UNARCHIVE_TEAM_2, and others.Salesforce (17 removed)
Salesforce (17 removed)
SALESFORCE_FETCH_MODIFIED_OR_UNMODIFIED_SOBJECTS, SALESFORCE_GET_A_BATCH_OF_RECORDS, SALESFORCE_GET_CONSENT_ACTION, SALESFORCE_GET_ORG_LIMITS, SALESFORCE_GET_QUICK_ACTIONS, SALESFORCE_GET_SEARCH_LAYOUT, SALESFORCE_GET_S_OBJECTS, SALESFORCE_PARAMETERIZED_SEARCH_POST, SALESFORCE_POST_COMPOSITE_TREE_SOBJECTNAME, SALESFORCE_SEARCH_RESULT_LAYOUTS, SALESFORCE_S_OBJECT_COLLECTIONS_CREATE, SALESFORCE_S_OBJECT_USER_PASSWORD, and others.GitHub (8 removed)
GitHub (8 removed)
GITHUB_LIST_CHECK_RUNS_FOR_A_GIT_REFERENCE, GITHUB_LIST_COMMIT_STATUSES_FOR_A_REFERENCE, GITHUB_LIST_SUBSCRIPTIONS_FOR_THE_AUTHENTICATED_USER, GITHUB_LIST_ASSIGNED_ISSUES, GITHUB_UPDATE_INFORMATION_ABOUT_A_GITHUB_PAGES_SITE, GITHUB_GET_GITHUB_GRAPHQL_META, GITHUB_GET_VIEWER_GRAPHQL_ID, GITHUB_LOOKUP_USER_BY_LOGINHubSpot (7 removed)
HubSpot (7 removed)
HUBSPOT_DELETE_CONTACT_FOR_GDPR_COMPLIANCE, HUBSPOT_GDPR_DELETE, HUBSPOT_PERMANENTLY_DELETE_CONTACT_FOR_GDPR, HUBSPOT_PERMANENTLY_DELETE_CONTACT_GDPR_COMPLIANCE, HUBSPOT_PERMANENTLY_DELETE_GDPR_CONTACT_AND_CONTENT, HUBSPOT_GET_MARKETING_EMAILS, HUBSPOT_GET_WORKFLOW_EMAIL_CAMPAIGNSCanvas (13 removed)
Canvas (13 removed)
CANVAS_GET_USERS_SELF_CONTENT_SHARES_RECEIVED, CANVAS_CREATE_USERS_SELF_CONTENT_SHARES, CANVAS_DELETE_USERS_SELF_CONTENT_SHARES, CANVAS_GET_A_SINGLE_GROUP, CANVAS_GET_COURSES_PREVIEW_HTML, CANVAS_GET_GROUPS_PREVIEW_HTML, CANVAS_GET_TERM, CANVAS_GET_USERS_SELF_CONTENT_SHARES, CANVAS_LIST_AVAILABLE_TABS_FOR_COURSE_2, CANVAS_LIST_USERS_IN_ACCOUNT, CANVAS_MARK_MODULE_ITEM_AS_DONE_NOT_DONE, CANVAS_RESOLVE_PATH, CANVAS_UPDATE_USERS_SELF_CONTENT_SHARESOther apps
Other apps
Renamed enum slugs
We’ve renamed 1,445 tool enum slugs across 37 toolkits to be more concise and agent-friendly. Old slugs contained verbose patterns likeDELETE_A_GIST, GET_A_CODESPACE_FOR_THE_AUTHENTICATED_USER, or ADD_MEMBERS_FOR_PROJECT. New slugs follow a cleaner APP_VERB_NOUN convention: DELETE_GIST, GET_CODESPACE, ADD_MEMBERS_TO_PROJECT.PostHog (179 renamed)
PostHog (179 renamed)
Stripe (161 renamed)
Stripe (161 renamed)
GitHub (156 renamed)
GitHub (156 renamed)
Pipedrive (156 renamed)
Pipedrive (156 renamed)
Shopify (132 renamed)
Shopify (132 renamed)
Outlook (70 renamed)
Outlook (70 renamed)
Supabase (65 renamed)
Supabase (65 renamed)
Trello (63 renamed)
Trello (63 renamed)
HubSpot (61 renamed)
HubSpot (61 renamed)
Box (58 renamed)
Box (58 renamed)
Slack (48 renamed)
Slack (48 renamed)
Salesforce (41 renamed)
Salesforce (41 renamed)
Vercel (39 renamed)
Vercel (39 renamed)
Twitter (36 renamed)
Twitter (36 renamed)
Google Analytics (25 renamed)
Google Analytics (25 renamed)
ClickUp (23 renamed)
ClickUp (23 renamed)
Microsoft Teams (22 renamed)
Microsoft Teams (22 renamed)
One Drive (21 renamed)
One Drive (21 renamed)
Dropbox (18 renamed)
Dropbox (18 renamed)
Google Drive (15 renamed)
Google Drive (15 renamed)
Firecrawl (11 renamed)
Firecrawl (11 renamed)
Jira (11 renamed)
Jira (11 renamed)
Asana (5 renamed)
Asana (5 renamed)
Icypeas (5 renamed)
Icypeas (5 renamed)
Attio (4 renamed)
Attio (4 renamed)
Linear (3 renamed)
Linear (3 renamed)
PeopleDataLabs (3 renamed)
PeopleDataLabs (3 renamed)
Gmail (2 renamed)
Gmail (2 renamed)
Google Calendar (2 renamed)
Google Calendar (2 renamed)
Reddit (2 renamed)
Reddit (2 renamed)
YouTube (2 renamed)
YouTube (2 renamed)
Apollo (1 renamed)
Apollo (1 renamed)
Facebook (1 renamed)
Facebook (1 renamed)
Google Docs (1 renamed)
Google Docs (1 renamed)
Google Sheets (1 renamed)
Google Sheets (1 renamed)
Hyperbrowser (1 renamed)
Hyperbrowser (1 renamed)
Telegram (1 renamed)
Telegram (1 renamed)
Migration
If you are usinglatest toolkit versions or fetching tools dynamically, no action is required.If you reference tool enums by name in your code:- Deprecated tools — update to the replacement listed above at your convenience. The old enum still works but will show a deprecation notice.
- Removed tools — switch to the canonical tool for that operation. The removed tool’s functionality is fully covered.
- Renamed enums — update any hardcoded enum strings to the new names.
mcp.composio.dev Deprecated Endpoint Removed
We’ve permanently removed the deprecatedmcp.composio.dev endpoint that was deprecated in November 2025.This endpoint was part of our early MCP integration experiments and the latest MCP offering from Composio is Composio For You (access 1000+ apps through one MCP).What Changed
- All traffic to
mcp.composio.devweb page now redirects to composio.dev/toolkits - The underlying service has been fully decommissioned
- No action needed if you’re using our current MCP
Migrating?
If you were still using the old endpoint, head to https://dashboard.composio.dev/~/org/connect to get started with the new MCP.Questions? Reach out to support@composio.devCustom Tools and Toolkits (Experimental)
You can now create custom tools and toolkits that run locally alongside remote Composio tools within a session.SDK Version
What’s New
Custom tools support three patterns — standalone tools for internal logic, extension tools that wrap Composio toolkit APIs with business logic, and custom toolkits that group related tools. TypeScript uses builder functions with Zod schemas; Python uses decorators with Pydantic annotations.- TypeScript
- Python
SessionContext
Every custom tool’sexecute receives (input, ctx):- TypeScript —
ctx.userId,ctx.proxyExecute(params),ctx.execute(toolSlug, args) - Python —
ctx.user_id,ctx.proxy_execute(...),ctx.execute(tool_slug, arguments)
Limitations
- Native tools only — custom tools work with
session.tools(). MCP support is coming soon. - Experimental API — the custom tool APIs and session
experimentaloption may change. - SDK-specific DX is intentional — TypeScript uses builder helpers and Zod. Python uses decorators, docstrings, and Pydantic annotations.
CLI Improvements: Login, Link, and Whoami
This release improves the Composio CLI with a better login flow, a non-blocking link option, and improved security for the whoami command.CLI Version
What’s New
Interactive Org/Project Picker After Login
composio login now prompts you to select your default organization and project after the browser OAuth flow completes.- Default behavior: After login, you see an interactive picker to choose your org and project. If you have only one org and one project, they are auto-selected.
- With
-y: Skip the picker and use the session defaults (e.g. for CI or scripts).
Non-Interactive Link with --no-wait
composio link now supports a --no-wait flag for non-blocking authorization flows.- Default: Opens the browser and waits until the connected account is ACTIVE.
- With
--no-wait: Prints link info and JSON to stdout (JQ-parseable) and exits immediately. Useful for scripts and CI.
Whoami No Longer Exposes API Keys
Thecomposio whoami command no longer displays API keys in the output. This improves security and reduces the risk of accidental exposure in logs or screenshots.- API key is removed from both display and JSON output.
- Hints for
composio manage orgs switchandcomposio initare shown instead.
Breaking Changes
Removed Flags from Login and Init
The following flags have been removed fromcomposio login and composio init:--api-key--org-id--project-id
Improvements
- Login JSON output: When using the org/project picker, the JSON output now reflects the final selection (not the initial session state).
- Picker error handling: If the org/project picker fails (e.g. API error), the CLI shows a warning, emits JSON with session data, and displays hints so you are not left without guidance.
- Modularized org/project selection: The selection logic is shared between
composio loginandcomposio manage orgs switch.
Polling Intervals: Transition Period for Existing Customers
We’re allowing a transition period before enforcing the new polling interval limits.Timeline
- Until May 1, 2026 — Existing customers continue to get 1-minute polling on all their triggers, including newly created ones.
- From May 1, 2026 — All triggers move to a 15-minute default polling interval. App-specific overrides will be available for apps with favorable rate limits.
Why 15 Minutes?
Composio-managed OAuth apps share rate limits across all users. At scale, 1-minute polling causes rate limiting and service degradation. The 15-minute minimum ensures reliability for everyone.How to Keep 1-Minute Polling
Set up your own OAuth app. With custom auth:- Intervals as low as 1 minute
- Your own rate limits
- No platform limits, ever
Polling Trigger Interval Changes
We’re updating polling trigger intervals to improve platform reliability and avoid rate limiting. This change affects how frequently polling triggers execute.What’s Changing?
Default Polling Interval
The default polling interval for triggers is increasing from 1 minute to 15 minutes.If you don’t specify aninterval in your trigger configuration, your triggers will now poll every 15 minutes instead of every 1 minute.Minimum Polling Interval
A new minimum polling interval of 15 minutes is being introduced. Triggers configured with intervals shorter than 15 minutes will be automatically clamped to 15 minutes.Current Behavior (Transition Period)
During the transition period, intervals below the minimum are silently clamped — your triggers will continue to work without errors, but they will run at the minimum interval instead of your requested interval.Enforcement (April 15, 2026)
Starting April 15, 2026, requesting an interval below the minimum will return an API error instead of silently clamping. Update your trigger configurations to use an interval of 15 minutes or higher before this date.App-Level Interval Overrides
We will also be introducing app-specific default polling intervals. Each app will have its own default interval based on the rate limits that app allows and whether the rate limit is per-user or per-app. These app-level defaults may be lower or higher than 15 minutes depending on the app. When you don’t specify aninterval, the app-level default will be used instead of the global 15-minute default.Need Intervals Below 15 Minutes?
If you require polling intervals shorter than 15 minutes, you should use your own OAuth app (custom auth). With custom auth, the 15-minute minimum does not apply — you can set polling intervals as low as 1 minute.What You Need to Do
- Review your trigger configurations — check if any triggers use intervals shorter than 15 minutes
- Update intervals to 15 minutes or higher before April 15, 2026
- If you need near-real-time events, consider using webhook triggers instead of polling triggers, or use custom auth for intervals as low as 1 minute
Rollout Timeline
- March 11, 2026: Silent clamping enabled — intervals below 15 minutes are automatically raised to 15 minutes
- April 15, 2026: API enforcement — intervals below 15 minutes will return an error
- April 15, 2026: Dashboard enforcement — the UI will prevent setting intervals below 15 minutes
MCP API Key Authentication Enabled by Default for New Orgs
As announced in our Optional API Key Enforcement for MCP Servers entry, MCP API key enforcement is now enabled by default for all newly created organizations.What’s Changed
From March 5, 2026, all projects in newly created organizations will haverequire_mcp_api_key set to true by default. Any MCP server request without a valid x-api-key header will be rejected with 401 Unauthorized.For New Organizations
- You can opt out by setting
require_mcp_api_key: falsein your project configuration
For Existing Organizations
Nothing changes for existing organizations. If your organization was created before March 5, 2026:- Your current
require_mcp_api_keysetting remains unchanged - You can opt in at any time through your project settings or via the API
Opting Out (New Organizations)
If you need to disable API key enforcement, setrequire_mcp_api_key: false during project creation or update it afterward:230+ Deprecated Tools Now Flagged Across 70+ Apps
Toolkit version:20260225_00 for all affected toolkitsTools with deprecated upstream API endpoints are now properly flagged with deprecated = True. This covers ~230 tools across 70+ apps — identified by cross-referencing official API documentation.All Deprecated Tools
Why This Matters
- Cleaner tool selection: Agents no longer see deprecated tools when browsing available tools, reducing confusion and failed tool executions
- No breaking changes: Deprecated tools are flagged, not removed — they’ll still work as long as the upstream API endpoint remains available
26 Toolkits Deprecated
26 toolkits have been deprecated — 7 for dead/defunct services and 19 that were duplicates, rebrands, or naming variants of existing toolkits.Dead Services (7)
These services are no longer operational:cloudpress, bench, leadoku, induced_ai, docnify, logoraisr, ncscaleDuplicates, Rebrands, and Naming Variants (19)
These toolkits were redundant with existing ones and have been deprecated in favor of the canonical version:Why This Matters
- Less confusion: Developers won’t accidentally pick a deprecated variant when a canonical toolkit exists
- Cleaner discovery: Toolkit listings now surface only the actively maintained version of each service
Slackbot Toolkit: Bot-Compatible Actions Only
Toolkit version:20260223_00The Slackbot toolkit inherits actions from the Slack toolkit. Previously, it included all 155 actions — but many of these were admin-only endpoints (admin.*) that require user tokens and don’t work with bot tokens.We’ve filtered the action list down to 89 bot-compatible actions — only actions whose Slack API endpoints are callable with a bot token.What Changed
Why This Matters
- Actions that work: Every action in the Slackbot toolkit now works with standard bot tokens
- Clearer scope: No more confusion about which actions require elevated permissions
- All triggers kept: Event-based triggers work with bot tokens and remain available
Removed Actions
The following action categories were removed because they require user tokens or admin permissions:admin.*endpoints (workspace administration)audit.*endpoints (audit logs)- SCIM endpoints (user provisioning)
Webhook V3 Now Default for New Organizations
As announced in our Webhook Payload V3 lookahead, Webhook Payload V3 is now the default for all newly created organizations.What’s Changed?
Starting today, every new organization created on Composio will automatically use Webhook Payload V3 for all webhook and Pusher deliveries. This means new organizations benefit from the improved webhook structure out of the box, with no additional configuration needed.For New Organizations
- Webhook payloads follow the Standard Webhooks specification
- Trigger data is cleanly separated from Composio metadata via the
metadataanddatafields - The
x-composio-webhook-version: V3header is included in all webhook deliveries
For Existing Organizations
Nothing changes for existing organizations. If your organization was created before today:- You will continue to receive webhooks in your current format (V1 or V2)
- You can opt-in to V3 at any time through your project settings
V3 Payload Recap
How to Switch to V3 (Existing Organizations)
- Go to your project settings in the Composio dashboard
- Navigate to the Webhooks section
- Select Webhook Payload Version: V3
- Update your webhook handlers using the migration guide
- Test thoroughly before enabling in production
Removal of Composio Managed Credentials for Twitter Toolkit
Composio managed credentials for the Twitter toolkit have been removed. Going forward, developers will need to provide their own Twitter API credentials to continue integrating Twitter into their applications.What’s Changing?
Previously, Composio provided managed credentials for the Twitter toolkit, allowing developers to use Twitter integrations without setting up their own Twitter API credentials. This managed credential support has now been removed.Impact
If you were relying on Composio managed credentials for the Twitter toolkit, your Twitter integrations will no longer work until you configure your own credentials.Migration
To continue using the Twitter toolkit, you will need to:- Create a Twitter Developer account and obtain your own API credentials from the Twitter Developer Portal.
- Set up a custom auth configuration with your Twitter API credentials in Composio.
Standardized Toolkit Categories
We’ve standardized the category taxonomy across all toolkits. Previously, categories were inconsistently applied with variations in naming and structure. Now, every toolkit is assigned categories from a well-defined set that can be extended as needed.What Changed
All toolkits have been recategorized using a standardized set of categories:AI & Automation: Artificial Intelligence, AI Agents, AI Assistants, AI Chatbots, AI Content Generation, AI Document Extraction, AI Meeting Assistants, AI Models, AI Safety Compliance Detection, AI Sales Tools, AI Web Scraping, Model Context ProtocolBusiness & Commerce: Business Intelligence, Analytics, Dashboards, Reviews, Commerce, Accounting, eCommerce, Fundraising, Payment Processing, Proposal & Invoice Management, TaxesCommunication: Communication, Call Tracking, Email, Fax, Notifications, Phone & SMS, Team Chat, Team Collaboration, Video ConferencingContent & Files: Content & Files, Documents, File Management & Storage, Images & Design, Notes, Transcription, Video & AudioHuman Resources: Human Resources, Education, HR Talent & RecruitmentIT & Development: IT Operations, Databases, Developer Tools, Online Courses, Security & Identity Tools, Server Monitoring, Internet of ThingsLifestyle: Lifestyle & Entertainment, Fitness, Gaming, News & LifestyleMarketing: Marketing, Ads & Conversion, Drip Emails, Email Newsletters, Event Management, Marketing Automation, Social Media Accounts, Social Media Marketing, Transactional Email, URL Shortener, WebinarsProductivity: Productivity, Bookmark Managers, Calendar, Product Management, Project Management, Spreadsheets, Task Management, Time Tracking SoftwareSales & Support: Sales & CRM, Contact Management, CRM, Forms & Surveys, Scheduling & Booking, Signatures, Support, Customer Appreciation, Customer SupportWeb & Apps: Website & App Building, App Builder, Website BuildersWhy This Matters
- Better discovery: Find relevant toolkits faster with consistent categorization
- Cleaner filtering: Filter toolkits by category in the dashboard and API with predictable values
- Extensible: New categories can be added as the toolkit ecosystem grows
API Impact
Thecategories field in toolkit responses now returns values from this standardized set. If you’re filtering toolkits by category, update your queries to use the new category names.Granola, monday.com, Context7, and Wix Toolkits
We’ve shipped four new toolkits in the first wave of external MCPs now available as native toolkits in Composio. Use them directly for tool calling or via Tool Router.New Toolkits
- Granola: AI meeting notes that transcribe and summarize calls into structured notes.
- monday.com: Work management platform for projects, tasks, and team workflows.
- Context7: Up-to-date library documentation and code examples for LLMs.
- Wix: Build and manage projects with business solutions like eCommerce, Bookings, and Payments in a few prompts via AI tools (Cursor/Claude) through the Wix MCP server.
75+ More Toolkits Get Typed Responses & Consistent Response Schema Wrapping
We’ve expanded typed response coverage to 75+ additional toolkits. In total, over 130 toolkits now return strongly typed response objects. Additionally, we’ve standardized response schema wrapping so that all action responses consistently nest their output under a top-leveldata field.Consistent Response Schema Wrapping
Previously, actions whose response schema already contained adata field at the root level would surface all fields (including data) alongside successful and error at the top level. Now, all action responses are uniformly wrapped: the full response object is nested inside a data field, with successful and error at the top level.Affected: Toolkits with data in their response model (e.g., Pipedrive PIPEDRIVE_LIST_UPDATES_ABOUT_A_DEAL)
These actions had a data field in their original response schema. Previously, those fields were spread at the root level alongside successful and error. Now, they are nested under a top-level data field.Before:result["data"]), update it to access them under result["data"]["data"] instead.Not affected: Toolkits without data in their response model (e.g., GitHub GITHUB_GET_THE_LATEST_RELEASE)
These actions never had a data field in their original response schema, so their wrapping behavior is unchanged. The response fields are nested under data as before.Affected Toolkits (280+)
Affected Toolkits (280+)
75+ Newly Typed Response Toolkits
All outputs for these toolkits now return strongly typed objects with clear field documentation instead of genericresponse_data blobs. Combined with the 60+ toolkits typed in the previous release, over 130 toolkits now have typed responses.Newly Typed Toolkits (78)
Newly Typed Toolkits (78)
Developer & DevOps
bitquery, docusign, hookdeck, metabase, neon, parsera, postgrid, sentry, servicenowCommunication & Collaboration
dailybot, dialpad, gleap, gong, googlemeet, retellai, smtp2goCRM & Business
bamboohr, coupa, forcemanager, lever, mixpanel, monday, okta, peopledatalabs, pipedrive, productboard, workdayMarketing & Analytics
amplitude, datagma, diffbot, lemlist, mailerlite, posthog, remarkety, resend, retently, sendgridAI & Automation
bolna, multionaiMedia & Entertainment
giphy, soundcloud, spotify, spotlightrReal Estate & Location
acculynx, apaleo, foursquare, foursquare_v1, foursquare_v2, hotspotsystemE-commerce & Payments
moneybird, open_sea, plisio, zoho_inventoryEducation & Learning
blackboard, canvas, d2lbrightspace, habiticaProject Management
pagerduty, shortcut, taskade, wrike, workspaceProductivity & Personal
borneo, box, cal, etermin, formdesk, google_admin, junglescout, klipfolio, onepage, strava, typefully, wakatime, zenrows, zoho, zoho_mailOther
semanticscholarWebhook Subscriptions API & Connection Expiry Events
A new API for managing webhook configurations with event filtering, HMAC signature verification, and support for platform lifecycle events. This replaces the legacy project-level webhook settings with a more flexible, subscription-based model.Summary
API Overview
See the Webhook Subscriptions API Reference for complete details.Endpoints
Key Capabilities
- Event filtering: Subscribe only to events you need
- HMAC-SHA256 signatures: Every webhook includes a cryptographic signature for verification
- Secret rotation: Rotate signing secrets on demand
Creating a Subscription
Notes
- 1 subscription per project: Currently limited to one webhook subscription per project. This will be expanded in future releases.
- HTTPS required: Webhook URLs must use HTTPS in production environments.
New Event: composio.connected_account.expired
A new platform event that notifies you when an OAuth2 connected account’s authentication expires and cannot be automatically refreshed.Use Cases
- Prompt users to re-authenticate before workflows fail
- Track connection health across your user base
- Automate re-connection flows
- Build proactive notification systems
Subscribing to Connection Expiry Events
Payload Structure
Thecomposio.connected_account.expired event follows the V3 envelope format:data object matches the response from GET /api/v3/connected_accounts/{id}, making it easy to process with existing code and SDK types.Verifying Webhook Signatures
All webhooks include an HMAC signature in thewebhook-signature header. Use the SDK’s built-in verification functions or see the Triggers documentation for implementation details.Available Event Types
Query available events and their version compatibility:Deprecations
Deprecated Endpoints
The following legacy endpoints are deprecated and will be removed in a future release:Deprecated Fields in Project Response
Backward Compatibility
What We’ve Done For You
- Automatic migration: We’ve created a webhook subscription for all existing projects that had webhook URLs configured, with
composio.trigger.messageenabled by default - Same payload format: If you were using V1, V2, or V3 triggers, they continue with the same format
What Continues to Work
- Legacy webhook endpoints (deprecated but functional)
- Existing project webhook configurations
- All existing trigger payload formats (V1, V2, V3)
- Signature verification with your existing secret
Payload Version Comparison
Limit Parameter Now Prevents Important Flag Auto-Apply
Version Information
TypeScript/JavaScript
- Package:
@composio/coreand all provider packages - Version:
0.6.3+ - PR: #2570
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 bothtoolkits 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:Auto-Apply Logic
Theimportant flag is now auto-applied only when ALL of these conditions are met:toolkitsis providedtoolsis NOT providedtagsis NOT providedsearchis NOT providedlimitis NOT provided ← NEWimportantis NOT explicitly set tofalse
Examples
Auto-Applies Important (No Limit)
Does NOT Auto-Apply (Limit Provided)
Explicit Important Overrides
Prevents Auto-Apply (Tags Provided)
Prevents Auto-Apply (Search Provided)
Why This Matters
When you provide alimit, 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:- Pagination: Get exactly N tools per page
- Performance: Limit tool count for faster responses
- 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
importantfiltering withlimit, you now need to explicitly passimportant: true
Documentation
Full documentation with more examples is available in the Tools API Reference.Expanded Typed Responses with GitHub, Mailchimp & Trello - Planning Further Expansion
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 genericresponse_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
Newly Typed Toolkits & Enhanced Coverage
Newly Typed Toolkits & Enhanced Coverage
Newly Typed Toolkits (3)
github, mailchimp, trelloEnhanced Existing Toolkits
Additional typed actions added to:Communication & Collaboration
discordbot, microsoft_teams, slack, zoomCRM & Sales
apollo, attio, hubspot, instantly, intercom, kommo, salesforceProductivity & Docs
coda, confluence, googledocs, googletasks, notion, todoistMarketing & Social Media
facebook, instagram, klaviyo, linkedin, metaads, reddit, tiktokE-commerce & Payments
brex, quickbooks, ramp, shopify, square, stripe, xeroProject Management
clickup, linearDesign & Creative
canva, figmaData & Analytics
ahrefs, airtable, apify, exa, pplx, serpapi, tavilyEmail & Calendar
calendly, outlookStorage & Files
one_driveWeb Tools
firecrawl, fireflies, google_maps, google_search_consoleAI & Media
elevenlabs, heygen, lmnt, mem0Customer Support
freshdesk, zendeskVideo & Content
youtubeComing Soon: 40+ More Toolkits
We’re planning to expand typed response coverage to 40+ additional toolkits in upcoming releases.Upcoming Typed Response Toolkits
Upcoming Typed Response Toolkits
Developer & DevOps
bitquery, clickhouse, composio, contentful_graphql, docusign, hookdeck, metabase, neon, parsera, postgrid, sentry, servicenowCommunication & Collaboration
dailybot, dialpad, gleap, gong, googlemeet, plain, retellai, smtp2goCRM & Business
bamboohr, coupa, forcemanager, lever, mixpanel, monday, okta, peopledatalabs, pipedrive, productboard, workdayMarketing & Analytics
amplitude, datagma, diffbot, lemlist, mailerlite, posthog, remarkety, resend, retently, sendgridAI & Automation
affinda, agentql, bolna, entelligence, kadoa, multionaiMedia & Entertainment
giphy, soundcloud, spotify, spotlightrReal Estate & Location
acculynx, apaleo, foursquare, foursquare_v1, foursquare_v2, hotspotsystemE-commerce & Payments
moneybird, open_sea, plisio, zoho_inventoryEducation & Learning
blackboard, canvas, d2lbrightspace, habiticaProject Management
pagerduty, shortcut, taskade, wrike, workspaceProductivity & Personal
borneo, box, cal, etermin, formdesk, formbricks, google_admin, junglescout, klipfolio, onepage, strava, typefully, wakatime, zenrows, zoho, zoho_mailOther Services
cults, faceup, semanticscholarType-Safe get_tools() for Python SDK
The Python SDK’sComposio class is now generic over the provider type. When you pass a provider to Composio(), the return type of tools.get() is automatically inferred based on that provider.SDK Versions
What Changed
Before: The return type oftools.get() was always untyped or required manual type annotations.After: Type checkers (mypy, Pyright) automatically infer the correct tool type from the provider you pass.Before (untyped):Automatic Type Inference
TheComposio class now uses Python generics to provide type-safe return values:Custom Provider Support
Custom providers automatically get proper type inference without requiring any changes to the Composio SDK:Supported Providers
Type inference is supported for all built-in providers:Backward Compatibility
This change is fully backward compatible:- Existing code continues to work without modifications
- Type inference is opt-in via static type checkers
- No runtime behavior changes
- No migration required
Simplified Schemas for Optional Fields
Tool schemas are now cleaner for optional fields by removing redundantanyOf: [{type}, {type: "null"}] constructs.Background: How JSON Schema Handles Optional Fields
In JSON Schema, there are two distinct concepts: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 therequired array, the schema processing now:- Removes the redundant
{type: "null"}fromanyOfarrays - Removes
default: nullsince it’s implied by being optional - Flattens single-type
anyOfto directtypedeclarations
Before vs After
For example, thepage_token field in GOOGLECALENDAR_LIST_CALENDARS (which is optional/not required):Previous (verbose):What’s Preserved
- Required nullable fields: Fields in the
requiredarray that accept null still useanyOfwith null type - Union types: Fields accepting multiple value types (e.g.,
string | number) retain their fullanyOfarray
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
anyOfconstructs - Clearer semantics: Non-required fields don’t need explicit null type—being optional already implies they can be omitted
SDK 0.6.0 Major Update: Cloudflare Workers Support and Breaking Changes
Version Information
TypeScript/JavaScript
- Package:
@composio/coreand all provider packages - Version:
0.6.0+
Python
- Package:
composioand 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: #2361The 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
TheverifyWebhook() method has two breaking changes: it’s now async AND requires additional parameters.Before:- ⚠️ Now async - Must use
await - ⚠️ New required parameter:
id(fromwebhook-idheader) - ⚠️ New required parameter:
timestamp(fromwebhook-timestampheader) - ⚠️ Header name changed:
x-composio-signature→webhook-signature - ⚠️ Return type changed:
TriggerEvent→VerifyWebhookResult
- 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:- ✅ Still synchronous (no
awaitneeded) - ⚠️ 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)
2. Mastra v1 Provider Update
PR: #2433The@composio/mastra provider has been updated to support Mastra v1, which has breaking API changes from v0.x.Before (Mastra v0.x)
After (Mastra v1)
Changes Required
- Update Mastra dependency:
npm install @mastra/core@latest - Update provider initialization: Pass Mastra instance to provider
- Update tool handling: Mastra v1 uses different tool schema format
- Check Zod version: Mastra v1 supports both Zod v3 and v4
- Check Node.js version: Mastra v1 requires Node.js v22.13.0 or higher
Major Features
3. Platform-Specific File Tool Modifier
PR: #2437Separate 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
composio.triggers.verifyWebhook() became async in Breaking Change #1. Node.js node:crypto is mostly synchronous, but the standard globalThis.crypto (Web Crypto API) available in Cloudflare Workers is async. To support both platforms with a single API, the method had to become async.4. Platform-Specific Config Defaults
PR: #2437Different default configurations for different runtimes to optimize behavior.Changed theautoUploadDownloadFiles default configuration for the Cloudflare Workers runtime, to avoid triggering runtime errors on unsupported features.Cloudflare Workers defaults:- Zero config for common use cases
- Optimized for each platform’s strengths
- Override defaults when needed
5. Node Buffer → Uint8Array Refactoring
PR: #2438Allnode: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
node:buffer and node:crypto enables Cloudflare Workers support. Cloudflare Workers don’t have access to Node.js built-in modules, so we use Web Standard APIs (Uint8Array, globalThis.crypto) that work in both Node.js and Cloudflare Workers.Bug Fixes
6. Tool Fetching with Specific Version
PR: #2518Fixed issues when executing tools with version constraints.Before (Bug)
After (Fixed)
7. Python JSON Schema Default Values
PR: #2506Fixed type coercion for stringified default values in JSON schemas.Before (Bug)
After (Fixed)
8. Salesforce Type Error Fix
PR: #2426FixedSALESFORCE_CREATE_LEAD type error with custom_fields parameter.Before (Bug)
After (Fixed)
anyOf and allOf JSON Schema constructs in Python SDK.Migration Guide
Step 1: Update Dependencies
- npm
- pnpm
- yarn
- pip
- uv
Step 2: Update Webhook Verification (Required)
- TypeScript
- Python
await:Step 3: Update Mastra Integration (If Using)
Only required if you use@composio/mastra provider- npm
- pnpm
- yarn
Step 4: Test Your Integration
- Run your test suite to catch any issues
- Test webhook verification if you use triggers
- Test file uploads/downloads - behavior improved but API unchanged
- 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
awaitAND addid+timestampparameters, update header names - ⚠️ Webhook verification (Python) - Must add
id+timestampparameters, 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:- ✅ 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
Getting Help
If you encounter issues during migration:- Check the docs: docs.composio.dev
- Join our Discord: discord.composio.dev
- Open an issue: github.com/ComposioHQ/composio/issues
- 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
Experimental Assistive Prompts and API 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.- Python
- TypeScript
experimental field is only available on sessions created with create(). Sessions retrieved with use() do not include the experimental data.Toolkit Endpoint Method
The toolkit retrieve response now includesgetCurrentUserEndpointMethod (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.- Python
- TypeScript
Impact Summary
Migration Guide
If you are using thepage parameter in listActive / list_active:- Replace
pagewithcursor - For the first request, omit the
cursorparameter or passundefined/None - Use the
nextCursor/next_cursorfrom the response for subsequent requests
Connected Account Initiate Now Filters by ACTIVE Status
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 callingconnectedAccounts.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)
After (Fixed)
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.File Upload/Download Fixes for latest tool with anyOf, oneOf, and allOf Schemas
Version Information
TypeScript/JavaScript
- Package:
@composio/coreand provider packages - Version:
0.5.3+
Python
- Package:
composioand 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.0.5.3 (TypeScript) or 0.10.8 (Python) or later to ensure file uploads and downloads work correctly with tools that use union or intersection types in their schemas.What Changed
Before (Bug)
File properties insideanyOf, oneOf, or allOf were not detected:After (Fixed)
File properties are now correctly detected and processed at any nesting level:Affected Scenarios
How to Update
TypeScript/JavaScript
- npm
- pnpm
- yarn
Python
- pip
- uv
- poetry
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
File handling in tool execution now uses presigned URLs
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
- Navigate to Project Settings in your Composio dashboard
- Find the File TTL configuration option
- Set your desired TTL value
Via API
Use the Update Project Config API to programmatically configure the file TTL: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
True PATCH Semantics for Auth Config Updates
Version Information
TypeScript/JavaScript
- Package:
@composio/coreand provider packages - Version:
0.5.1+
Python
- Package:
composio-coreand 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
credentials object is merged—send only the fields you want to change, and existing fields are preserved.New Capabilities
Rotate a Single Credential Field
Update justclient_secret without resending client_id or other fields:- Python
- TypeScript
Update Tool Restrictions Without Touching Credentials
Previously, this would fail becausecredentials was required. Now it works:- Python
- TypeScript
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
- Python
- TypeScript
Raw HTTP API
For users calling the API directly:Tool Router Improvements and New Features
Version Information
TypeScript/JavaScript
- Package:
@composio/coreand provider packages - Version:
0.3.4to0.4.0
Python
- Package:
composio-coreand provider packages - Version:
0.10.4to0.10.5
New Features
1. Wait for Connections Property
AddedwaitForConnections (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:2. Session-Specific Modifier Types
Introduced new modifier types for better session-based tool execution:SessionExecuteMetaModifiers and SessionMetaToolOptions.TypeScript:3. Dedicated Method for Tool Router Meta Tools
AddedgetRawToolRouterMetaTools (TypeScript) / get_raw_tool_router_meta_tools (Python) method in the Tools class for fetching meta tools directly from a tool router session.TypeScript: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
Tool Enum Name Shortening
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 usinglatest 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.Optional API Key Enforcement for MCP Servers
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
- All MCP requests must include the
x-api-keyheader 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):Enabling the Setting
Via Dashboard
- Navigate to Project Settings
- Go to the Project Configuration tab
- Find the “Require API Key for MCP” toggle
- Enable the toggle

Via API
Update your project configuration using the API:Via Code
- Python
- TypeScript
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
Update Setting
Consistent Error Response Structure
Tool execution errors now return a standardized response format across all failure types. Previously, thedata 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 (ornullfor non-HTTP errors)data.message: Detailed error messageerror: Same detailed message at the top level
Before vs After
Previous error response:Why This Matters
- Easier parsing: Agents and code can reliably access error details from
data.messagewithout special-casing emptydataobjects - 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 SchemaanyOf for union types, providing accurate type information for LLMs and code generators.What Changed
Two changes affect how types appear in request/response schemas:Toolkits with multi-type union fields (157 total)
Toolkits with multi-type union fields (157 total)
Before vs After
For example, theGOOGLECALENDAR_GET_CURRENT_DATE_TIME request schema changes: Previous (only a single type):page_token in GOOGLECALENDAR_LIST_CALENDARS:Previous: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
Deprecating BEARER_TOKEN auth scheme for 19 toolkits
We’ve deprecated theBEARER_TOKEN auth scheme for the following 19 toolkits:AirtableDiscordDiscordbotGmailGoogle ClassroomGoogle Search ConsoleGoogle CalendarGoogle DocsGoogle DriveGoogle SlidesGoogle SuperInstagramNtfySapling AISlackSlackbotTawk ToTikTokTwitter
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_TOKENwill continue to function. - Creating new auth configs and connected accounts with
BEARER_TOKENwill continue to work (e.g., via API/SDK). - To discourage new usage,
BEARER_TOKENauth configs / connected accounts will not be displayed in the UI for these toolkits.
Webhook Payload V3 - Lookahead Announcement
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:Payload Structure
The payload structure is being reorganized to separate Composio metadata from trigger data:Before (V2):Key Improvements
- Metadata Separation: Composio-specific fields (connection IDs, trigger IDs, user IDs) are now in a dedicated
metadataobject - Clean Data: The
datafield now contains only the actual trigger payload without infrastructure metadata - Standardized Type Field: The
typefield now follows a consistent format (composio.trigger.message) instead of trigger-specific names likegmail_new_gmail_message - Trigger Slug in Metadata: The trigger slug (e.g.,
GMAIL_NEW_GMAIL_MESSAGE) is now available inmetadata.trigger_slugfor easy identification - Standards Compliance: Follows Standard Webhooks specification for better interoperability
- 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:Checking Webhook Version
You can detect the webhook version from headers: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
- Go to your project settings in the Composio dashboard
- Navigate to the Webhooks section
- Select “Webhook Payload Version: V3”
- Update your webhook handlers to use the new structure
- Test thoroughly before enabling in production
Benefits
- Better DX: Clear separation between metadata and actual trigger data
- Standards Compliance: Follows industry-standard webhook specifications
- Consistency: Same structure across webhooks and Pusher channels
- Future-Proof: Built on established standards for long-term compatibility
Need Help?
If you have questions about migrating to V3 or need assistance:- Join our Discord community
- Check our documentation
- Contact support at support@composio.dev
Binary Data Support for Proxy Execute
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
Upload File via Base64 Content
Supported up to 4MB file size.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
File Download Response
Summary
Authentication & Configuration Updates Across Multiple Toolkits
Summary
This release includes significant authentication and configuration improvements across 16+ toolkits. The changes standardize Base URL handling, modernize authentication methods, and fix various endpoint configurations to improve reliability and flexibility.Breaking Changes
We verified that active usage for these toolkits is practically zero before proceeding with these changes.Make Toolkit
- Removed Region field in favor of explicit Base URL configuration
- Users must now provide the full Base URL instead of selecting a region
- This change provides more flexibility for custom deployments and regional endpoints
Bubble Toolkit
- Removed Subdomain field and restructured Base URL handling
- Users must now provide the complete Base URL instead of just the Subdomain
- This change standardizes URL configuration across all toolkits
Deprecated Features
HelloBar Toolkit
- Bearer authentication is now deprecated
- While still functional, users are encouraged to migrate to newer authentication methods
- Support for bearer tokens will be removed in a future release
FormSite Toolkit
- Bearer authentication deprecated in favor of API key authentication
- New integrations should use API key authentication for improved security
- Existing bearer token implementations will continue to work but should be migrated
Improvements & Fixes
Configuration Improvements
Linear Toolkit - Base URL is no longer a configurable field. The toolkit now uses a fixed endpoint, simplifying the authentication process.Kibana Toolkit - Removed the default value for Base URL, allowing for more flexible deployment configurations. Users can now specify custom Kibana instances without overriding defaults.Gong Toolkit - Added a sensible default value for Base URL to simplify initial setup. New users can connect without manually configuring the endpoint.Insightly Toolkit - Added default value for the Pod field to streamline configuration. Reduces setup complexity for standard deployments.ClickUp Toolkit - Fixed the Base URL field type for proper validation and handling. Ensures consistent URL formatting across all operations.Dynamic Endpoint Updates
Brilliant Directories Toolkit - Implemented dynamic Base URL resolution for the Get Current User Endpoint. Automatically adapts to different deployment environments.Braintree Toolkit - Updated configuration to use production defaults. Implemented dynamic endpoint resolution for better environment handling. Improved reliability for production deployments.Auth0 Toolkit - Replaced hardcoded endpoints with dynamic tenant-based URL resolution. Supports multi-tenant deployments without manual configuration. Automatically constructs the correct endpoint based on the tenant configuration.Endpoint Fixes
DataScope Toolkit - Fixed the Get Current User Endpoint to use the correct API path. Resolves authentication verification issues.D2L Brightspace Toolkit - Updated the Get Current User Endpoint to match the latest API specifications. Ensures proper user identification and session validation.Migration Guide
For toolkits with breaking changes, please update your configurations as follows:- Make: Replace Region with the full Base URL (e.g.,
https://us-east-1.make.com) - Bubble: Replace Subdomain with the full Base URL (e.g.,
https://myapp.bubbleapps.io)
- HelloBar & FormSite: Generate new API keys from your account settings and update your authentication configuration
Authentication Updates Across Multiple Toolkits
We’ve updated authentication configurations for several toolkits to improve security, fix issues, and support additional deployment options.Summary
Breaking Changes
These toolkits had incorrect or outdated authentication configurations that needed fixing. We verified that active usage for these toolkits is practically zero before proceeding with these changes.Impact: Existing connections will stop working. You’ll need to create new auth configs and ask affected users to reconnect.Make
Replaced region-based configuration with full base URL input. Users now provide the complete Make instance URL (e.g.,https://us2.make.com or https://us1.make.celonis.com) instead of just a region code.Recall AI
Updated from region-based to full base URL configuration. Fixed field descriptions and metadata. Updated categories to AI/Productivity/Communication and added proper documentation links.Relevance AI
Simplified authentication by removing deprecated Project ID field. Added conditional mapping for region codes to API subdomains (AU→f1db6c, EU→d7b62b, US→bcbe5a). Region field now defaults to US.SmartRecruiters
Fixed OAuth configuration with correct SmartRecruiters endpoints. Added proper default scopes for candidates, jobs, and users. Enabled PKCE and added refresh token support.Deprecated (Still Working)
These changes introduce new auth methods while keeping old ones functional:Ashby
Added new API Key authentication scheme with automatic base64 encoding and proper authorization headers.No Action Required: Old Basic Auth method is deprecated but continues to work. Existing connections are unaffected.Freshdesk
Added new API Key authentication scheme requiring subdomain and API key with automatic base64 encoding.No Action Required: Old Basic Auth method is deprecated but continues to work. Existing connections are unaffected.Freshservice
Added new API Key authentication scheme requiring subdomain and API key with automatic base64 encoding.No Action Required: Old Basic Auth method is deprecated but continues to work. Existing connections are unaffected.Trello
Marked Bearer Token authentication as deprecated in favor of OAuth authentication.No Action Required: Old Bearer auth continues to function. OAuth is recommended for new connections.ZoomInfo
Added new OAuth2 authentication scheme with comprehensive scopes for contacts, companies, audiences, scoops, news, and intent data. Deprecated the old JWT-based Basic authentication. Password field now properly marked as secret.No Action Required: Old JWT auth continues to function. New connections will use OAuth2.Non-Breaking Improvements
Mixpanel
Fixed region mapping logic for data residency. Added proper conditional evaluation to map regions to correct API hosts (EU, India, or Standard). Region field is now optional and defaults to Standard server. Service account secret now properly marked as secret.No Action Required: Existing connections continue to work without changes.Supabase
Changedbase_url field type from auth_config_field to connection_field for both OAuth and API Key schemes. Updated base action logic to respect user-provided base URLs, enabling support for self-hosted Supabase instances.No Action Required: Existing connections continue to work. Self-hosted instances now supported.Toolkit Deprecation: Removing Empty Toolkits
What’s Changed
We’re deprecating 15 toolkits that currently have no supported actions. These toolkits will be reactivated once we add functional actions to them, ensuring you only see integrations that are ready to use.Deprecated Toolkits
The following toolkits are now deprecated:BREATHEHR,DIXA,EGNYTE,EXPENSIFY,FREEAGENTGUSTO,NUTSHELL,OPENNUTRITION,OYSTERHR,RAKUTENSALESFLARE,TEAMLEADER,WALGREENS,WHOOP,WIX
Impact on Your Integration
API Behavior Changes
List Toolkits EndpointThe GET /toolkits endpoint will now exclude deprecated toolkits by default.Need to see deprecated toolkits? Use theinclude_deprecated query parameter.Backward Compatibility
Your existing integrations are safe. All other endpoints continue to work with deprecated toolkits:- Retrieve the toolkit details
- Create auth configurations
- Manage connected accounts
- Configure MCP Servers
Why This Matters
This change helps you:- Focus on working integrations - No clutter from non-functional toolkits
- Avoid integration attempts with toolkits that have no actions
- Better developer experience with a cleaner, more actionable toolkit list
Questions?
If you have questions or need support with any deprecated toolkit, reach out to our team or check our documentation.Toolkit Deprecation: Streamlining Our Platform
What’s Changed
We’re deprecating 60 toolkits that currently have no supported actions. These toolkits will be reactivated once we add functional actions to them, ensuring you only see integrations that are ready to use.Deprecated Toolkits
The following toolkits are now deprecated:ACCELO,ADOBE,AERO_WORKFLOW,AMAZON,APEX27APPOINTO,APPSFLYER,ATLASSIAN,AUTH0,AXONAUTBATTLENET,BOLDSIGN,BRAINTREE,BREEZY_HR,BREX_STAGINGBRIGHTPEARL,BROWSERHUB,CUSTOMER_IO,DEEL,DRIP_JOBSEPIC_GAMES,FACTORIAL,FITBIT,FRONT,GO_TO_WEBINARGURU,HELCIM,HIGHLEVEL,ICIMS_TALENT_CLOUD,IDEA_SCALEKEAP,LASTPASS,LEVER_SANDBOX,LEXOFFICE,MANY_CHATMBOUM,MICROSOFT_TENANT,MOXIE,ONCEHUB,POPTINPRECORO,PRINTNODE,QUALAROO,RAVENSEOTOOLS,RING_CENTRALRIPPLING,SAGE,SALESFORCE_MARKETING_CLOUD,SEISMIC,SMARTRECRUITERSTAPFORM,TERMINUS,TIMEKIT,TWITCH,VENLYVERO,VISME,WAVE_ACCOUNTING,WIZ,ZOHO_DESK
Impact on Your Integration
API Behavior Changes
List Toolkits EndpointThe GET /toolkits endpoint will now exclude deprecated toolkits by default.Need to see deprecated toolkits? Use the newinclude_deprecated query parameter.Backward Compatibility
Your existing integrations are safe. All other endpoints continue to work with deprecated toolkits:- Retrieve the toolkit details
- Create auth configurations
- Manage connected accounts
- Configure MCP Servers
Why This Matters
This change helps you:- Focus on working integrations - No clutter from non-functional toolkits
- Avoid integration attempts with toolkits that have no actions
- Better developer experience with a cleaner, more actionable toolkit list
Questions?
If you have questions or need support with any deprecated toolkit, reach out to our team or check our documentation.Deprecation of is_local_toolkit Field and Removal of is_local Query Parameter
We’re cleaning up the Toolkits API by deprecating theis_local_toolkit response field and removing the is_local query parameter filter.What’s Changing?
Response Field: is_local_toolkit (Deprecated)
The is_local_toolkit field in toolkit API responses is now deprecated. This field was originally intended to indicate whether a toolkit was local to a specific project, but it is no longer meaningful as no toolkits use this classification.Affected Endpoints:GET /api/v3/toolkits- List toolkitsGET /api/v3/toolkits/{slug}- Get single toolkitGET /api/v3/toolkits/multi- Get multiple toolkits
false. It is marked as deprecated: true in the OpenAPI specification.Query Parameter: is_local (Removed)
The is_local query parameter filter has been removed from the following endpoints:GET /api/v3/toolkitsGET /api/v3/toolkits/multi
Impact on Your Code
If You’re Using the is_local Query Parameter
Before:If You’re Reading the is_local_toolkit Response Field
The field will continue to be present in responses but will always return false. You can safely ignore this field or remove any logic that depends on it.Before:Tool Router General Availability
The Composio SDKs achieved a significant milestone with Tool Router moving from experimental to stable production status in December 2025. The Tool Router is now a fully supported feature that enables creating isolated MCP sessions with scoped toolkit access across both Python 0.10.1 and TypeScript 0.3.0.Major Achievements
Native Tool Execution: Both SDKs now support direct tool execution through Tool Router sessions. The TypeScript implementation emphasizes improved type safety and error handling, while Python developers benefit from better integration with provider-wrapped tools.Webhook Security: A new verification method was introduced. The system now provides secure webhook endpoint validation and signature verification for incoming webhooks, enhancing protection for trigger-based workflows.Framework Compatibility: The stable Tool Router integrates with multiple AI platforms including OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, and Vercel AI SDK.Technical Improvements
The TypeScript SDK resolved significant CommonJS compatibility issues by switching bundlers. This addresses a common developer pain point, particularly for Node.js projects not using ES modules.The Python SDK extended LangChain provider support to version 1, while simultaneously fixing a critical KeyError occurring when SUPABASE_BETA_RUN_SQL_QUERY is used with Agents.Migration Path
Users upgrading from experimental APIs should note the simplified approach—the Tool Router API now operates directly rather than through experimental namespaces, with comprehensive migration documentation provided.Typed Responses Across Toolkits
We’ve updated many toolkits so their outputs are now strongly typed objects instead of a genericresponse_data blob, meaning tools like Outlook, HubSpot, Notion, etc. now return well-shaped, documented fields you can rely on directly in your code and agents. These improvements apply to the latest toolkit versions—see our toolkit versioning docs for how versions are managed.Why This Matters
- Better developer experience for direct execute: clear fields and types
- Improved agent performance: flatter output shapes with explicit fields reduce nesting and invalid params
- Clearer docs and type safety: richer metadata for IDEs and autocomplete
Impacted Toolkits (57 total)
Impacted Toolkits (57 total)
Communication & Collaboration
discordbot, microsoft_teams, slack, zoomCRM & Sales
apollo, attio, hubspot, instantly, intercom, kommo, salesforceProductivity & Docs
coda, confluence, googledocs, googletasks, notion, todoistMarketing & Social Media
facebook, instagram, klaviyo, linkedin, metaads, reddit, tiktokE-commerce & Payments
brex, quickbooks, ramp, shopify, square, stripe, xeroProject Management
clickup, linearDesign & Creative
canva, figmaData & Analytics
ahrefs, airtable, apify, exa, pplx, serpapi, tavilyEmail & Calendar
calendly, outlookStorage & Files
one_driveWeb Tools
firecrawl, fireflies, google_maps, google_search_consoleAI & Media
elevenlabs, heygen, lmnt, mem0Customer Support
freshdesk, zendeskVideo & Content
youtubeBefore vs After
Previous (generic, version20251202_00):20251209_00):dashboard.composio.dev → Toolkits → List Messages (or the relevant tool).Migration Notes
- Breaking change for consumers on the
latestversion who post-process the old nestedresponse_datashape: outputs are now flattened and explicitly typed. - New and modified fields include richer descriptions and examples; some legacy placeholders were removed.
- Re-fetch schemas for your tool/version to see the typed definitions. Use the toolkit view in
dashboard.composio.devfor authoritative field details.
Removal of label query parameter from connected accounts API
Thelabel query parameter has been removed from the GET /api/v3/connected_accounts endpoint.What’s changing?
Thelabel query parameter is no longer supported when listing connected accounts. This parameter was previously accepted but had no functional behavior since label ingestion was removed in an earlier update.Impact
None - This is a cleanup change. Thelabel query parameter was not performing any filtering since the underlying label ingestion functionality was already removed. If your code was passing this parameter, it was being silently ignored.Migration
No action required. If your code was passing thelabel query parameter, you can safely remove it from your API calls.Enhanced Security Masking for Sensitive Fields
We’ve improved the security masking forREDACTED fields in the following APIs:What’s Changed: Sensitive fields are now partially masked, revealing only the first 4 characters to help with debugging while maintaining security.Example:Disabling Masking
If you need to disable masking for your use case, you have two options:- Via UI: Navigate to Project Settings → Configuration tab and update the masking settings
- Via API: Use the Patch Project Config API
Transition to Self-Managed Credentials for Select Applications
What’s Changing?
Starting today, the following applications will require your own developer credentials instead of Composio-managed credentials:- Auth0
- Blackbaud
- BoldSign
- Deel
- Front
- GoToWebinar
- PagerDuty
- Pipedrive
- Shopify
- Strava
- SurveyMonkey
- Webex
What You Need to Do
To continue using these applications with Composio:- Create Developer Accounts: Register for developer accounts on the platforms you need
- Generate API Credentials: Create OAuth apps following each platform’s documentation
- Configure in Composio: Add your credentials to Composio using custom auth configs
- Test Your Integration: Test your integration with the new credentials
Connected Account Expiration for Incomplete Connections
We’re implementing automatic expiration for connected accounts that remain in incomplete states, helping maintain a cleaner and more efficient authentication system.What’s Changing?
Connected accounts inInitializing and Initiated states will now automatically expire after 10 minutes. This applies to connection attempts that were started but never completed.Why This Matters
This change provides:- Better Resource Management: Automatically cleans up incomplete connection attempts
- Improved System Hygiene: Prevents accumulation of stale, unused connection records
- Enhanced User Experience: Reduces clutter from abandoned authentication flows
Questions?
If you have any questions about this change, please reach out to our support team or check our Connected Accounts documentation.Required API Key Authentication for MCP URLs
We’re strengthening the security of Model Context Protocol (MCP) URLs by making API key authentication mandatory for all requests.What’s Changing?
Starting December 15th, 2025, all new Composio projects must include thex-api-key header when making requests to MCP URLs. This header authenticates your application and ensures secure communication with the Composio platform.Why This Matters
This change provides:- Enhanced Authentication: Ensures only authorized applications can access MCP endpoints
- Industry Best Practices: Aligns with standard API security patterns
Impact on Existing Projects
For existing projects: We value backward compatibility and understand the need for a smooth transition. Your existing MCP URLs will continue to work without thex-api-key header until April 15th, 2026.Important: After April 15th, 2026, all MCP URL requests without the x-api-key header will be rejected. Please ensure you update your applications before this date to avoid service disruption.Note: If you’re already passing the x-api-key header in your MCP requests, no action is required—you’re all set!Migration Guide
To adopt this security enhancement in your existing projects:- Locate Your API Key: Find your API key in the Composio dashboard under Project Settings
- Update Your Code: Add the
x-api-keyheader to all MCP URL requests - Test Thoroughly: Verify the updated requests work in your development environment
- Deploy: Roll out the changes to your production environment
Questions?
If you have any questions about this security enhancement or need assistance with migration, please reach out to our support team or check our MCP documentation.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_versionsparameter totriggers.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_versionsparameter totriggers.create()method- Uses global toolkit version configuration when creating trigger instances
- Converts
Nonetoomitfor 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: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):Enhanced MCP URL Security Requirements
We’re introducing improved security requirements for Model Context Protocol (MCP) URLs to ensure better isolation between user connections and prevent unauthorized access.What’s Changing?
Starting today, all new Composio projects must include at least one of the following parameters in their MCP URLs:user_id- Identifies the specific userconnected_account_id- Identifies the specific connected account
Why This Matters
This change ensures that:- User Isolation: Each user’s connections remain completely separate from others
- Enhanced Security: Prevents potential cross-user data access scenarios
- Better Multi-Tenancy: Enables safer multi-tenant application architectures
- Explicit Access Control: Forces developers to explicitly specify which user or account context they’re operating in
Impact on Existing Projects
For existing projects: We understand the importance of backward compatibility. While we’ve sent email notifications to project owners about upgrading their MCP URLs, your existing integrations will continue to work until January 15th, 2026.Important: After January 15th, 2026, MCP URLs withoutuser_id or connected_account_id query parameters will no longer be supported. Please ensure you update your MCP URLs before this date to avoid service disruption.Note: If your MCP URLs already include either user_id or connected_account_id query parameters, no action is required—you can safely ignore this notice.Implementation Example
Before:Migration Guide
If you’re using an existing project and want to adopt this security enhancement:- Review your current MCP URL configuration
- Add either
user_idorconnected_account_idparameter to your URLs - Update your application code to pass the appropriate identifier
- Test the updated URLs in your development environment
Questions?
If you have any questions about this security enhancement or need assistance with migration, please reach out to our support team or check our MCP documentation.Adds Version Checks for Tool Execution and Improved Execution Speed in TS SDK
Summary
Added version validation for manual tool execution to prevent unexpected behavior when usinglatest toolkit versions. This ensures users explicitly specify toolkit versions when executing tools manually, while allowing flexibility through a skip flag.This release also eliminates a lot of redundant API calls made to check connected account during tool execution, effectively increasing the performance of tool execution.Key Changes
Python SDK (python/)
- Added
ToolVersionRequiredErrorexception with detailed error messages and fix suggestions - Added
dangerously_skip_version_checkparameter toexecute()method - Modified
_execute_tool()to validate version is notlatestunless skip flag is set - Automatically passes
dangerously_skip_version_check=Truefor agentic provider flows - Added comprehensive test coverage (19 test methods) in
test_tool_execution.py
TypeScript SDK (ts/packages/core/)
- Added
ComposioToolVersionRequiredErrorerror class with possible fixes - Added
dangerouslySkipVersionCheckparameter to execute flow - Modified tool execution to validate version before API calls
- Updated execution type definitions in
tool.types.tsandmodifiers.types.ts - Updated test files with date-based version format (
20251201_xx) - Improved tool execution by eliminating redundant API calls
Behavior
Before: Tools could be executed withlatest version, risking unexpected behavior on toolkit updatesAfter: Manual execution requires specific version or explicit skip flag:Breaking Changes
Manual tool execution without version specification now throws an error. Users must either:- Pass explicit version parameter
- Configure toolkit versions in SDK initialization
- Set environment variable
COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG> - Use
dangerously_skip_version_check=Trueflag
MCP (Model Control Protocol) & Experimental ToolRouter
Composio now introduces comprehensive MCP (Model Control Protocol) support and an experimental ToolRouter for creating isolated, scoped sessions with advanced toolkit management. These features enable seamless integration with modern AI frameworks and provide powerful session-based tool routing capabilities.Why Use MCP & ToolRouter?
- Framework Integration: Native MCP support for Vercel AI, Mastra, OpenAI Agents, and LangChain
- Session Isolation: Create isolated sessions with specific toolkit configurations
- Advanced Authentication: Flexible auth config management per toolkit
- Scoped Access: Control which tools are available within each session
- Multi-Service Workflows: Route tool calls efficiently across different services
- Development & Testing: Perfect for testing and development with scoped MCP server access
TypeScript SDK (v0.1.53)
Added: MCP API
Core MCP Features:- MCP Server Creation: Create and manage MCP server configurations
- User-Specific URLs: Generate unique MCP server URLs for individual users
- Toolkit Configuration: Support for multiple toolkits with custom auth configs
- Tool Filtering: Specify allowed tools per configuration
- Connection Management: Choose between manual and automatic account management
Added: Experimental ToolRouter
Core ToolRouter Features:- Session-Based Routing: Create isolated sessions for specific users and toolkit combinations
- Dynamic Configuration: Configure toolkits and auth configs per session
- MCP Server URLs: Each session gets a unique MCP server endpoint
- Flexible Toolkit Management: Support for string names or detailed toolkit configurations
- Connection Control: Manual or automatic connection management per session
Python SDK (v0.8.17)
Added: MCP Support
Core MCP Features:- Server Configuration: Create and manage MCP server configurations
- Toolkit Management: Support for both simple toolkit names and detailed configurations
- Authentication Control: Per-toolkit auth config specification
- Tool Filtering: Specify allowed tools across all toolkits
- User Instance Generation: Generate user-specific MCP server instances
Added: Experimental ToolRouter
Core ToolRouter Features:- Session Management: Create isolated tool routing sessions for users
- Toolkit Configuration: Support for both simple toolkit names and detailed configurations
- Session Isolation: Each session gets its own MCP URL and session ID
- Flexible Authentication: Per-session auth config management
- Scoped Tool Access: Control which tools are available within each session
Migration Guide
TypeScript SDK: Migrating to New MCP API
The new MCP API provides enhanced functionality and better integration patterns. Here’s how to migrate from the previous MCP implementation:Before (Legacy MCP)
After (New MCP API)
Key Migration Changes
- Two-Step Process:
- Before: Single step server creation
- After: Create configuration, then generate user instances
- Enhanced Configuration:
- Before: Simple toolkit names only
- After: Detailed toolkit configs with auth, tool filtering, connection management
- User-Specific URLs:
- Before: Single server URL for all users
- After: Unique URLs per user for better isolation
- Backward Compatibility:
- Legacy Access: Old MCP functionality remains available via
composio.deprecated.mcp - Gradual Migration: Migrate at your own pace without breaking existing implementations
- Legacy Access: Old MCP functionality remains available via
Migration Benefits
- Better Security: User-specific sessions with isolated access
- Enhanced Control: Fine-grained toolkit and tool management
- Framework Integration: Native support for modern AI frameworks
- Scalability: Better resource management and user isolation
Migration Timeline
- Phase 1: New MCP API available alongside legacy implementation
- Phase 2: Legacy MCP accessible via
deprecated.mcpnamespace - Phase 3: Full deprecation (timeline to be announced)
Key Benefits & Use Cases
Development & Testing
- Isolated Environments: Test different toolkit combinations without affecting production
- Scoped Access: Limit tool access for security and testing purposes
- Framework Flexibility: Works with any MCP-compatible client or framework
Production Workflows
- Multi-Service Integration: Seamlessly combine tools from different services
- User-Specific Sessions: Each user gets their own isolated session with appropriate permissions
- Authentication Management: Fine-grained control over authentication per toolkit
Framework Compatibility
- Vercel AI: Native integration with Vercel AI SDK
- Mastra: Full support for Mastra agents and workflows
- OpenAI Agents: Direct integration with OpenAI’s agent framework
- LangChain: Complete LangGraph and LangChain compatibility
- Custom Clients: Works with any MCP-compatible client
Enterprise Features
- Session Management: Track and manage multiple user sessions
- Resource Control: Limit concurrent sessions and resource usage
- Audit Trail: Full logging and monitoring of tool usage
- Security: Isolated sessions prevent cross-user data access
Migration & Compatibility
Both MCP and ToolRouter features are designed to complement existing Composio functionality:Bug Fixes
Fixed: ToolRouter Dependency Issue
Python SDK (v0.8.19)Issue Fixed:- ToolRouter Functionality: Fixed ToolRouter tests that were failing due to missing
tool_routerattribute in HttpClient - Dependency Update: Updated
composio-clientdependency from version 1.9.1 to 1.10.0+ to include ToolRouter functionality - Version Compatibility: Resolved compatibility issues between ToolRouter implementation and client library
composio-client library version 1.9.1 did not include the tool_router attribute, causing all ToolRouter integration tests to fail with AttributeError: 'HttpClient' object has no attribute 'tool_router'.This has been fixed in version 0.8.19 by:- Updating the
composio-clientdependency to version 1.10.0+ - Ensuring all ToolRouter functionality is now available
- All ToolRouter integration tests now pass successfully
Fixed: Missing Descriptions in Auth Config Fields
Python SDK (v0.8.17) & TypeScript SDK (v0.1.53)Issue Fixed:- Auth Config Connection Fields: Added missing descriptions to toolkit auth configuration connection fields
- Auth Config Creation Fields: Added missing descriptions to toolkit auth configuration creation fields
- Field Documentation: Improved field documentation and help text for better developer experience
- Clear, descriptive field labels
- Helpful placeholder text where appropriate
- Detailed explanations of field requirements
Toolkit Versioning in SDKs
Composio Toolkit Versioning provides granular control over tool versions across all your integrations. Instead of always using the latest version of tools, developers can now specify exact toolkit versions, ensuring consistent behavior and controlled updates in production environments.Why Use Toolkit Versioning?
- Version Stability: Pin specific toolkit versions to avoid unexpected changes in production
- Controlled Updates: Test new toolkit versions before deploying to production
- Environment Consistency: Ensure the same toolkit versions across development, staging, and production
- Rollback Capability: Easily revert to previous toolkit versions if issues arise
- Fine-grained Control: Set different versions for different toolkits based on your needs
Python SDK (v0.8.11)
Added- Toolkit Versioning Support: New
toolkit_versionsparameter for controlling tool versions- Added
toolkit_versionsparameter toComposioclass initialization - Support for global version setting (e.g.,
'latest') - Support for per-toolkit version mapping (e.g.,
{'github': '20250902_00', 'slack': '20250902_00'}) - Environment variable support with
COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>pattern - New
toolkit_version.pyutility module for version resolution logic
- Added
TypeScript SDK (v0.1.52)
Added- Toolkit Versioning Support: Added
toolkitVersionsconfiguration option- New
toolkitVersionsparameter inComposioclass constructor - Support for global version string or per-toolkit version mapping
- Environment variable parsing with
getToolkitVersionsFromEnv()utility - Enhanced
getRawComposioToolBySlug()method for version-specific tool retrieval - Version-aware tool filtering and search capabilities
- New
Key Benefits
- Environment Variables: Set
COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>=<VERSION>for automatic version resolution - Flexible Configuration: Choose between global versions or per-toolkit version mapping
- Backward Compatibility: Existing code works unchanged - versioning is opt-in
- Version Fallback: Automatically falls back to ‘latest’ when no version is specified
- Cross-Platform Consistency: Identical developer experience across Python and TypeScript
Version Format
Toolkit versions follow the format:YYYYMMDD_NN (e.g., 20250902_00) or use 'latest' for the most recent version only supported at global scope and not individual toolkit level.Environment Variables
Migration Note
This feature is fully backward compatible. Existing code will continue to work without changes, using the latest versions by default. To enable versioning, simply add thetoolkit_versions parameter during SDK initialization.Additional Updates
- Package Updates: Bumped all Python provider packages to v0.8.10
- Documentation: Enhanced API documentation with versioning examples
- Testing: Added comprehensive test coverage (400+ new test cases) for versioning functionality
- Examples: New versioning examples demonstrating practical usage patterns
Introducing Composio Auth Links
Composio Auth Links provide a hosted authentication solution that eliminates the need for developers to build custom authentication forms. Instead of manually rendering OAuth consent screens, API key input forms, or custom authentication fields, developers can simply redirect users to a Composio-hosted URL that handles the entire authentication process automatically.Why Use Auth Links?
- Zero UI Development: No need to build forms for OAuth, API keys, or custom fields like subdomains
- Universal Authentication: Works seamlessly across all supported third-party services
- Reduced Complexity: Replace complex OAuth flows with a simple redirect
- Better UX: Professional, consistent authentication experience for end users
- Faster Integration: Get authentication working in minutes, not hours
Python SDK (v0.8.11)
Added- Composio Connect Link Support: New
link()method for creating external authentication links- Added
link()method toConnectedAccountsclass for generating user authentication links - Support for callback URL redirection after authentication
- Enhanced user experience with external link-based authentication flow
- No manual form rendering required - Composio handles all authentication UI
- Added
TypeScript SDK (v0.1.51)
Added- Composio Connect Links: Added support for composio connect links
- New
link()method inConnectedAccountsclass for generating authentication URLs - Support for callback URL redirection with
CreateConnectedAccountLinkOptions - Comprehensive TypeScript types and validation for link creation options
- Eliminates need for custom authentication forms - just redirect users to the link
- New
Key Benefits
- No Form Building: Composio handles OAuth consent, API key collection, and custom field inputs
- Hosted Authentication Flow: Professional UI that works across all supported services
- Callback URL Support: Control where users return after successful authentication
- Connection Waiting: Built-in polling to detect when authentication completes
- Cross-Platform Consistency: Identical developer experience across Python and TypeScript
Customisation
You can customise the app logo and name showed in the authentication page via the dashboard. Head over your project viadashboard.composio.dev and choose Settings → Auth Links to upload a new logo and change the name.Migration Note
This feature replaces manual authentication form development with a simple redirect-based approach, significantly reducing integration time and complexity while providing a better user experience. Auth links are drop in replacement forcomposio.connectedAccounts.initate, you can safely swap this to composio.connectedAccounts.link