## Summary
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
PR #4099 dropped 8 auth pages from meta.json. That was a net win for
machines (Loop 5 eval: 84/100 vs 77/100, tool-routing failure mode gone)
but it made the pages unreachable by clicking. PostHog, weekday-matched
and control-adjusted, shows the affected pages down 14-64pp beyond the
site-wide baseline drift.
Restore human navigation without touching the machine-facing wins:
- authentication.mdx becomes authentication/index.mdx and the 7 sibling
auth pages move into the folder. /docs/authentication keeps its URL
(fumadocs serves index.mdx at the folder route), so Core concepts
still shows one row and the top-level sidebar row count stays 20.
- shared-connections moves into extending-sessions: it is experimental
and is a session capability, not a core auth concept.
- "Migration and security" splits into "Migration" and "Security and
data" — separator headings, not clickable rows.
- Drop AUTHENTICATION_GUIDE_URLS from app/llms.txt/route.ts. The pages
are back in the page tree, so they emit automatically under Core
concepts -> Authentication; the hardcoded list would now duplicate.
- 8 permanent redirects for the old URLs (36-42% Google entry rate on
most of them), plus existing redirect destinations repointed so none
of them chain.
- ~90 inbound links rewritten across content, api-overviews, app, lib
and agent instructions. lint:links is the gate: 0 errors.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
---------
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
When a verifier URL is set, the OAuth handoff carries only session_uri and the
developer's endpoint owns the final redirect, so a callback_url passed at
connection creation is not used. One clause in the reference; regenerated both
index pages.
Same-browser binding is not enabled, so remove it from the connected-accounts
reference and concept map. Keep the OAuth session fixation definition as the
rationale for callback identity verification, which is now the single control
the section documents. Regenerated both index pages; repointed the concept map
to #callback-identity-verification.
- complete_auth is a v3.1-only endpoint (no v3 route), so drop the OAuth
connection security section from the v3 connected-accounts index; keep it on v3.1.
- status_reason on mismatch is the enum VALUE 'Callback identity verification
failed', not the key IDENTITY_VERIFICATION_FAILED. Fix both files.
- Changelog no longer claims Composio universally 'stops' the attack. It ships
two controls: same-browser binding (automatic on managed) and opt-in callback
identity verification.
Changelog: run through good-docs-writing — remove every em-dash, drop the salesy
'most reliable way', plainer confident voice.
connected-accounts overview + both index files: correct the completion outcomes.
Per completeFromSession, only an identity mismatch fails the connection (FAILED +
status_reason IDENTITY_VERIFICATION_FAILED); any other error leaves it pending so
the flow can be restarted; the session_uri is consumed either way. The old text
read as if the connection always moved to FAILED.
Drop the standalone /docs/oauth-connection-security page and its nav entry. The
content now lives as a section in the connected-accounts API overview
(api-overviews/connected-accounts.mdx), next to the complete_auth endpoint it
documents, in that overview's house style.
- Add the section (same-browser binding + callback identity verification) to the
overview and mirror it into both generated index.mdx files (v3.1 + v3). The
index generator's deps don't resolve in this worktree, so the mirror is manual;
it matches what generate:api-index would emit from the updated overview.
- Repoint the changelog and the agent concept map at
/reference/api-reference/connected-accounts#...
- Fix a stale concept-map claim: identity verification is opt-in per project and
covers every connection once set, not custom-auth-config-only.
## Summary
Implements the docs half of **PLEN-2793** — renders a typed public
reference for the payloads Composio delivers to customer webhook URLs,
under **API Reference → Webhook Events**.
Pairs with platform PR ComposioHQ/platform#11389, which generates the
spec.
## What's here
- **`docs/public/openapi-webhooks.json`** — the generated OpenAPI
**3.1** spec (top-level `webhooks`: `composio.trigger.message`,
`composio.connected_account.expired`, `composio.trigger.disabled`),
produced from the webhook payload Zod schemas in Apollo (SSOT). Finishes
the earlier untracked WIP: adds the missing `trigger.disabled` event and
reuses shared schemas as `$ref` (`WebhookEventEnvelope`,
`ConnectedAccountDetailed`).
- **`docs/lib/openapi.ts`** — adds the spec as a **second input** to the
v3.1 reference source. Fumadocs (`fumadocs-openapi`) renders the
`webhooks` block natively; operations group under the "Webhook Events"
tag at `api-reference/webhook-events/*`.
- **`webhook-events/index.mdx`** — landing page listing the three
events, cross-linked to the Webhook Subscriptions API and signature
verification.
## Why a separate 3.1 spec
`webhooks` is a 3.1-only top-level field; the main `openapi.json` is
3.0. A separate file keeps the main spec (and its sync pipeline)
untouched and avoids the docs' union-normalisation pass. See the
platform PR for the full rationale.
## Verified locally
- [x] `bun scripts/validate-links.ts` — **0 errors** (the generated
`handle_composio_*` webhook pages resolve; no collision with the
hand-authored `index.mdx`)
- [x] `bun test tests/static/` — 33 pass / 0 fail
- [x] `bun run types:check` — clean
## Notes
- Setup, subscription, and signature-verification docs already exist
(`setting-up-triggers/*`) and are cross-linked, not rewritten.
- Follow-up (optional): auto-sync the webhooks spec from Apollo on prod
deploy (currently committed by hand), mirroring the main-spec
`docs-update-data` pipeline.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`workflow_dispatch`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`) — latest v3.1 and v3.0 API specifications
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: sudodaksh <23355449+sudodaksh@users.noreply.github.com>
## Summary
Deprecated REST endpoints now surface the existing `Legacy` badge in
generated API-reference indexes, with endpoint-specific tooltip copy
instead of the Sessions-specific default. The generator behavior is
covered end to end for both v3 and v3.1, including rendered table
output.
This branch also restores CI compatibility with the organization Actions
policy: workflow tool versions still come from `mise.toml`, but
installation uses the approved, SHA-pinned setup actions. Secret
scanning pins the repaired organization reusable workflow from
ComposioHQ/.github#13.
## Changes
- Read the OpenAPI `deprecated` flag and emit `legacy: true` only for
deprecated operations.
- Render `LegacyBadge` on affected endpoint rows with accurate lifecycle
tooltip copy.
- Regenerate the affected `files` and `connected-accounts` indexes for
v3 and v3.1.
- Cover the real generator output, active-operation omission, badge
count, and tooltip through a focused regression test.
- Replace disallowed transitive Actions dependencies while retaining
`mise.toml` as the single tool-version source.
Endpoint detail pages continue to use `fumadocs-openapi`'s built-in
deprecated marker. The indexed endpoints are `GET /files/list` and `POST
/connected_accounts/{nanoid}/refresh`; internal operations remain
filtered from the docs.
## Spec data
The committed OpenAPI snapshots lagged the live backend for `POST
/connected_accounts/{nanoid}/refresh`. Both snapshots now carry its
current summary, description, and `deprecated: true`; the next
`fetch-openapi.mjs` run will preserve that state from the live spec.
## Validation
- `bun run test`: 25 passed, 0 failed.
- `bun run types:check`: passed.
- Focused ESLint and generated-index drift checks: clean.
- Composite-action and workflow YAML parsed successfully; extracted tool
pins match `mise.toml`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: jkomyno <alberto@composio.dev>
This PR:
- reverts https://github.com/ComposioHQ/composio/pull/3780
- restores the TypeScript `composio.create()` and `composio.use()`
session aliases, with their runtime and type-test coverage
- restores the prior deprecation state for
`BaseProvider.wrapMcpServerResponse`
- removes the pre-v1 breaking-change changeset so the release PR no
longer advertises this removal
The v1 API-freeze change should be recreated later as a draft PR and
kept out of the merge queue until v1 is ready.
## What and why
This makes the intended v1 API cleanup real rather than postponing it to
v2:
- Remove the TypeScript root aliases `composio.create(...)` and
`composio.use(...)`. Session creation and reuse now live only at
`composio.sessions.create(...)` and `composio.sessions.use(...)`. This
is a deliberate breaking change, reflected by a major changeset.
- Retain `BaseProvider.wrapMcpServerResponse` as the stable v1 provider
SPI. Its earlier deprecation pointed to a method that was never
introduced.
The scope is intentionally narrow: it does **not** remove unrelated
deprecated APIs, and Python keeps its supported `Composio.create/use`
API. The TypeScript docs, examples, providers, runtime fixtures,
generated SDK reference, and API-reference indexes now use the
namespaced TypeScript API. Historical changelog examples are left as
history.
## Verification
- `pnpm typecheck`
- `pnpm --filter @composio/core test -- --run test/core/session.test.ts`
(42 files, 1,018 tests)
- `pnpm exec eslint ts/packages/core/src/composio.ts`
- `pnpm --filter @composio/core generate:docs`
- `cd docs && bun run generate:api-index`
- `cd docs && bun run types:check`
- `git diff --check` and targeted scans for removed TypeScript aliases
I also attempted the affected Node and Cloudflare runtime E2E suites.
They cannot initialize in this checkout without `COMPOSIO_API_KEY` (and,
for Cloudflare, `COMPOSIO_BASE_URL` and `OPENAI_API_KEY`); they did not
report a product assertion failure.
## Summary
- Refresh the checked-in v3.1 and v3 OpenAPI snapshots from the live
backend specs using `bun run scripts/fetch-openapi.mjs`.
- Regenerate API reference index pages with `bun run
generate:api-index`.
- Surfaces `DELETE /api/v3.1/tool_router/session/{session_id}` in the
Tool Router API reference.
- Includes the other upstream generated spec changes from the same
auto-fetch, including generated API Keys and Organization Management
section indexes.
## Verification
- `bun run scripts/fetch-openapi.mjs`
- `bun run generate:api-index`
- `git diff --check`
- `bun run build`
## Notes before merge
- This is intentionally the full auto-generated OpenAPI refresh, not the
surgical two-file patch.
- The generated backend OpenAPI still contains some `internal` wording
in descriptions; left as-is to preserve the auto-generated output.
- Confirm the newly generated API Keys / Organization Management
sections are intended to publish with this refresh.
---------
Co-authored-by: jkomyno <alberto@composio.dev>
Integration branch for the next docs release: a **sessions-first
documentation rewrite** — new and rewritten guides, example pages,
interactive components, and docs tooling — plus the supporting SDK
changes that the new docs describe.
The bulk of this PR is docs (~24k lines across ~150 commits); the SDK
changes (~5k lines) back the new guides.
## Documentation (the bulk)
- **Sessions-first restructure** — reorganized navigation and section
structure (incl. the "Sandbox (prev workbench)" section), with
v3-reorganization redirects so old URLs keep resolving.
- **Rewritten core guides** — quickstart, configuring sessions, triggers
(creating + subscribing to events), proxy-execute, toolkits
enable/disable, and common FAQ, rewritten in the house voice.
- **New example pages** — local-sandbox PR reviewer, daily standup bot,
and slack bot, with runnable build-ups.
- **New interactive components & diagrams** — triggers flow animation,
manage-connections visual, connection-refresh visual, and the
terminal-kit components.
- **Docs tooling** — a docs-graph link-graph connectivity checker,
search reprioritization (deprioritize legacy pages), and SDK-reference
regeneration.
## Supporting SDK changes
**`@composio/core` → 0.13.0 (minor)**
- `composio.sessions.create()` as the first-class sessions API
(`composio.create()` kept as an alias).
- **MCP is opt-in:** default `create()` / `use()` return native-tool
sessions (`SessionWithoutMcp`); pass `{ mcp: true }` to surface
`session.mcp`. _Migration: read `session.mcp` only after creating with
`{ mcp: true }`._
- `session.sandbox` is the canonical resolved config;
`session.workbench` kept as a deprecated alias. `sandbox` is the
preferred session-config key (`workbench` still accepted).
- `connectedAccounts.updateAcl()` graduated from experimental (alias
kept).
- `triggers.parse()` (parse + optionally verify an incoming webhook) and
`triggers.setWebhookSubscription()`.
**`@composio/experimental` → minor** — local-workbench helpers moved
onto the `@composio/experimental/workbench` subpath (out of
`@composio/core/experimental`), keeping the ~14 KB embedded Python
helper out of core. Plus the experimental Pi provider.
**`@composio/slim` → minor.**
**Python → 0.17.0** — mirrors the TS surface: `composio.sessions` mount
(`tool_router` deprecated), `triggers.parse()` /
`set_webhook_subscription()`, the `sandbox` config key, and
`connected_accounts.update_acl()`.
## Review response (#3664)
Addressed the `@composio/core` review:
- **Security:** `triggers.parse()` no longer fails open — a
present-but-empty `verifySecret` (e.g. unset `COMPOSIO_WEBHOOK_SECRET`)
now throws instead of silently skipping verification; omitting it stays
an explicit opt-out (both SDKs).
- Removed snake_case leakage from `transformWebhookSubscription` (+ the
index signature that allowed it).
- **Removed** the TS-only `connectedAccounts.link()` toolkit
auto-resolve (shipped with cancellability / orphaned-auth-config bugs
and was effectively undocumented; to be reintroduced properly later).
- Unified Python error types on `ValidationError`; added `mcp=True`
Python tests; fixed runtime-portability + error-type test assertions.
- Polished deprecation messages; fixed the backwards `/experimental`
`@deprecated` note and the `SessionWithMcp` JSDoc.
## Testing
- **TS:** `@composio/core` + `@composio/experimental` typecheck pass;
vitest green for the touched suites.
- **Python:** `test_tool_router.py` + `test_triggers.py` pass (161
tests).
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Kshitij Jhunjhunwala <kj@composio.dev>
Co-authored-by: Malay Vasa <malayvasa@gmail.com>
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
Apollo split the Webhooks tag into Webhook Subscriptions + Webhook Endpoints, so /reference/api-reference/webhook-subscriptions and /webhook-endpoints are the canonical pages now. Repoint:
- glossary, creating-triggers, subscribing-to-events, webhook-verification, and the webhook-subscriptions changelog
- delete the orphan /reference/api-reference/webhooks/index.mdx (and its v3 twin) — Apollo's openapi.json no longer routes any operation to the legacy Webhooks tag, but generate-api-index iterates only tags-with-operations, so the orphan never got auto-removed (separate script bug, follow-up)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`) — latest v3.1 and v3.0 API specifications
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/reference/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
- Re-fetch OpenAPI spec which now includes v3.1 tool endpoints (hermes#8990)
- Update fetch-openapi.mjs to remove older API versions when a newer one
exists for the same endpoint path (e.g. v3 hidden when v3.1 available)
- Update generate-api-index.ts with the same version deduplication logic
- Regenerate API reference index pages
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fumadocs-openapi uses operationId (e.g., getToolRouterSessionBySessionId)
not slugified summaries for page URLs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Each endpoint now shows:
- HTTP method (GET, POST, PATCH, DELETE)
- Full path with parameters
- Linked title
- Full description from OpenAPI spec
Much more useful for LLMs to understand the API.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Instead of flat files like `auth-configs.mdx`, generate as
`auth-configs/index.mdx` so they become the index page for
each API folder, avoiding duplicate sidebar entries.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create generate-api-index.ts script that reads OpenAPI spec
- Generate simple markdown index pages for each API tag
- Pages include tag description and links to all endpoints
- Run automatically as prebuild step
- Update overview page with links to index pages
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add authentication page explaining API key usage
- Add errors page with HTTP status codes and error types
- Add rate limits page with plan-based limits and headers
- Improve overview page with REST API table and SDK cards
- Set API Reference and SDK Reference folders to expand by default
- Remove navigation footer from OpenAPI reference pages
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh