@devries-cameron20 / composio Mirror · read-only / commits / 5ee907f4c
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 09:45 UTC

docs: toolkit version deprecation and sunset (#4881)

## What Adds a "Deprecation and sunset" section to `docs/content/docs/tools-direct/toolkit-versioning.mdx` (50 lines of MDX): Composio-managed toolkit versions are deprecated 12 months after publish and retired 3 months after that, the newest version is never deprecated, what the `Composio-Deprecated-Toolkits` response header looks like and which routes carry it, the exact SDK warning text for Python and TypeScript with how to silence it, how to move to a newer version (cross-linked to the existing pinning sections on the page), and the `410 Gone` after the sunset date. The section's anchor is the `<DOCS_URL>` both SDK warnings point at: `https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset` ## Why Phase 1 of toolkit version deprecation (PLEN-2553; platform #13516, #13517) emits the header and the SDK PRs warn with a link to this section. `migration-guide/toolkit-versioning.mdx` covers the v0.9 / v0.2 required-version change and does not overlap, so nothing was duplicated there. ## Notes - No Phase 2 (410) page exists on the site yet, so the sunset behaviour is one sentence. - The sunset in the example header, `@1787788800`, is 2026-08-27 UTC (the handoff's prose said 2026-08-23; the page uses the value the epoch actually encodes, matching the SDK formatters). - No em dashes in the added text. ## Checks run From `docs/` with the mise toolchain (`bun 1.4.3`), after `bun install`: - `bun run lint`: 5 pre-existing warnings in unrelated `.tsx` / `.mjs` files, none in the changed page. - `bun run lint:links`: `0 errored file, 0 errors`. - `bun run test`: `715 pass, 0 fail` across 67 files. - `bun run types:check`: KB generation, agent index, `fumadocs-mdx`, `next typegen` and `tsc --noEmit` all clean. - `bun run build`: `next build` exit 0. ## Sibling PRs - TypeScript: https://github.com/ComposioHQ/composio/pull/4883 - Python: https://github.com/ComposioHQ/composio/pull/4884 Linear: PLEN-4352 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

sankaran-lab committed Oct 15, 2026 at 18:34 UTC 5ee907f4c6025eedb3d7c79e903566da42660338
1 file changed +50
docs/content/docs/tools-direct/toolkit-versioning.mdx
+50
@@ -207,6 +207,56 @@ console.log("Latest Version:", toolkit.meta.availableVersions?.[0]);
207
208 Call `composio.toolkits.changelog()` in Python or `await composio.toolkits.changelog()` in TypeScript to retrieve the last 10 versions for each toolkit. The response's `items` contain each toolkit's slug and version entries, which you can review before changing a pinned version.
209
210 +## Deprecation and sunset
211 +
212 +Composio-managed toolkit versions are deprecated 12 months after they're published and retired 3 months after that. The newest version of a toolkit is never deprecated, so pinning a current version and upgrading on your own schedule keeps you clear of both dates.
213 +
214 +When a request resolves to a deprecated version, the API adds a `Composio-Deprecated-Toolkits` response header alongside the normal response:
215 +
216 +```http
217 +Composio-Deprecated-Toolkits: "GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle"
218 +```
219 +
220 +The header is an RFC 9651 structured-field list. Each item names the toolkit slug and the resolved `version`, plus optional `deprecated` and `sunset` dates (Unix seconds, prefixed with `@`) and a `reason`. Versions deprecated by hand carry only `version`.
221 +
222 +Single-toolkit routes carry the header: toolkit get, tool get, tool execute, text-to-request, trigger type get, trigger upsert and setup, and trigger authorization entities. Listing endpoints never do.
223 +
224 +### SDK warning
225 +
226 +Both SDKs read the header and warn once per process for each deprecated toolkit version. The call still succeeds.
227 +
228 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
229 + <Tab value="Python">
230 +```text
231 +[Deprecation] Toolkit GMAIL version 20250114_00 was deprecated on 2026-05-27 (lifecycle) and will stop working on 2026-08-27. Pin a newer version with toolkit_versions={"gmail": "<version>"} or COMPOSIO_TOOLKIT_VERSION_GMAIL. See https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset.
232 +```
233 +
234 +The warning is a `ComposioDeprecationWarning` (a `UserWarning` subclass), so standard warning filters apply:
235 +
236 +```python
237 +import warnings
238 +from composio import ComposioDeprecationWarning
239 +
240 +warnings.filterwarnings("ignore", category=ComposioDeprecationWarning)
241 +```
242 + </Tab>
243 + <Tab value="TypeScript">
244 +```text
245 +[Deprecation] Toolkit GMAIL version 20250114_00 was deprecated on 2026-05-27 (lifecycle) and will stop working on 2026-08-27. Pin a newer version with toolkitVersions: { gmail: '<version>' } or COMPOSIO_TOOLKIT_VERSION_GMAIL. See https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset.
246 +```
247 +
248 +The warning goes through the SDK logger at the `warn` level. Silence it with `logLevel: 'error'` in the constructor or `COMPOSIO_LOG_LEVEL=error` in the environment.
249 + </Tab>
250 +</Tabs>
251 +
252 +When the header omits `reason` or `sunset`, the warning omits those clauses too.
253 +
254 +### Moving off a deprecated version
255 +
256 +Pick a newer version from the [dashboard](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=docs-tools-direct-toolkit-versioning) or `toolkits.get()`, then pin it the same way you pin any version: at [SDK initialization](#sdk-initialization), through an [environment variable](#environment-variables), or [per execute call](#per-execution-override). The warning stops as soon as requests resolve to a version that isn't deprecated.
257 +
258 +After the sunset date, requests for the retired version fail with HTTP `410 Gone` until you pin a supported version.
259 +
260 ## Next
261
262 <Card icon={<Wrench />} title="Fetching tools" href="/docs/tools-direct/fetching-tools" description="Fetch and filter tools, inspect schemas, and search semantically" />