## Summary
Automated documentation updates triggered by new changelog entries
merged to next.
Generated by Codex via GitHub Actions.
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Follow-up to #2941. The "Renamed enum slugs" section of the 2026-03-28
changelog
(`docs/content/changelog/03-28-26-tool-consolidation-enum-renames.mdx`)
lists 347 Old Enum → New Enum pairs that don't line up with the actual
class-name-derived slugs delivered by mercury PR #17949 (commit
`12d585aa7e`, "fix: rename low-usage action class names to cleaner
slugs"). This PR replaces that section with the verified table.
### How slugs are formed
```python
enum = inflection.underscore(cls.__name__).upper()
slug = enum if enum.startswith(TOOLKIT) else f"{TOOLKIT}_{enum}"
```
Slug is derived from the **class name** of the action, not the file name
and not the `name` attribute. (Source: `mercury/tools/_base/action.py`
`set_metadata` / `set_tool`.)
### Audit results vs. existing docs section
| Category | Count |
|---|---|
| Original docs pairs that match PR #17949 exactly | 291 |
| Pairs with **wrong New Enum** (PR's actual new differs) | 1 |
| Pairs whose **old class never existed** in any commit | 5 |
| Pairs that refer to renames done in **other PRs** (or tool removals) |
20 |
| Pairs claiming a rename **that never happened** (old class still
present at HEAD with original slug) | 30 |
| **Real PR #17949 renames missing from docs and still valid at HEAD** |
**1,153** |
| Total entries originally listed | 347 |
| Total entries in this rewrite | **1,445** |
### Notable corrections
- `SUPABASE_UPDATES_PROJECT_S_SUPAVISOR_CONFIG` → docs said
`SUPABASE_UPDATE_SUPAVISOR_CONFIG`; **actual** is
`SUPABASE_UPDATE_PROJECT_SUPAVISOR_CONFIG` (class
`UpdateProjectSupavisorConfig` at
`apps/supabase/actions/generated/updates_project_s_supavisor_config.py`).
- `SLACK_DELETE_MESSAGE` is **not a real slug**. The chat-deletion
action is class `DeletesAMessageFromAChat`, slug
`SLACK_DELETES_A_MESSAGE_FROM_A_CHAT`. Removed from the table.
- All eight `PIPEDRIVE_*A_*` entries (`ADD_A_DEAL`, `ADD_A_NOTE`,
`DELETE_A_PERSON`, `GET_DETAILS_OF_A_PERSON`,
`LIST_PARTICIPANTS_OF_A_DEAL`, `UPDATE_A_DEAL`, `UPDATE_A_LEAD`,
`UPDATE_A_PERSON`) still exist at HEAD with their original slugs —
removed from the renames table.
- 14 Slack entries that claimed renames (e.g. `SLACK_FETCH_TEAM_INFO` →
`SLACK_GET_TEAM_INFO`) were never executed; class names still match the
original slug. Removed.
- Whole toolkits previously omitted that PR #17949 actually renamed and
that remain valid at HEAD: PostHog (179), Trello (63), Salesforce (41),
Vercel (39), Twitter (36), Google Analytics (25), Dropbox (18), Icypeas
(5), Reddit (2), YouTube (2), Apollo, Facebook, Hyperbrowser, Telegram
(1 each).
### Front-matter description / intro paragraphs
Updated count from "1,545 enum slugs across 24 toolkits" → "1,445 enum
slugs across 37 toolkits" to match the rewritten table.
### Out of scope
This PR does **not** change the "Deprecated tools" or "Consolidated
(removed) tools" sections — those describe a different consolidation
effort and are unrelated to the class-rename audit.
## Test plan
- [ ] Spot-check 10–20 random entries from the rewritten table against
the actual class definition in `mercury` (`apps/<toolkit>/actions/`) to
confirm `inflection.underscore(cls.__name__).upper()` matches the listed
New Enum.
- [ ] Confirm `<Accordions>...</Accordions>` block renders correctly on
`docs.composio.dev` preview.
- [ ] Confirm none of the 30 "rename never happened" entries listed in
the audit show up in the new table.
---------
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary\n- show project API key permission endpoints with
/api/{version}/... placeholders instead of duplicating versioned rows\n-
keep proxy execute documented for direct and session proxy paths\n\n##
Verification\n- bun run lint:links from docs/\n- git diff --check
## What
Removes the incorrect `alias` references from the initiate-to-link
migration guide
(`docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx`).
## Why
The `alias` parameter does **not** exist on either method:
- TS: `composio.connectedAccounts.link()` /
`composio.connectedAccounts.initiate()`
- Python: `composio.connected_accounts.link()` /
`composio.connected_accounts.initiate()`
This was verified against the SDK source and the generated client. The
doc should not claim the parameter exists. Real alias/label support may
be added later; this change only corrects the docs for now.
## Changes
- Dropped `alias` from the sentence: `` `callback_url` / `callbackUrl`
works the same way on both methods. ``
- Deleted the `` | `alias` | ✓ | ✓ | `` row from the comparison table.
No other content changed (`callback_url`, `allow_multiple`, `config`
rows are intact).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
- Add a Notion FAQ entry for connection expiry reasons.
- Cover user-initiated revocation/removal from Notion workspace
connections.
- Cover the same-user/same-OAuth-app reconnection pattern that can leave
older Composio-managed connections with stale tokens.
## Validation
- `git diff --check`
- `bun run scripts/validate-links.ts` could not run because `bun install
--frozen-lockfile` fails with existing docs lockfile drift: `lockfile
had changes, but lockfile is frozen`.
## Summary
The TypeScript SDK reference generator (`generate-docs.ts`) strips every
`api/vN/...` substring from JSDoc descriptions to keep raw endpoint
paths out
of user-facing docs. The blanket regex also strips paths that live
**inside
intentional inline-code spans**, mangling them.
Concretely, `ConnectedAccounts.initiate()`'s JSDoc:
> The legacy `` `POST /api/v3/connected_accounts` `` endpoint that this
method …
currently renders in the generated reference as:
> The legacy `` `POST `` endpoint that this method …
— content lost and an unclosed code span. (Visible today in
`docs/content/reference/sdk-reference/typescript/connected-accounts.mdx`.)
## Fix
In `extractDescription`, split the text on inline-code spans and only
strip
bare API paths **outside** backticks; deliberate route references inside
code
spans are left intact. The path regex is also tightened to stop at
code-span
and punctuation boundaries (`` ` ``, `)`, `,`, `.`, `;`).
The single affected reference page is regenerated in the same commit.
## Verification
- `pnpm --filter @composio/core generate:docs` → only
`connected-accounts.mdx`
changes, restoring the full `` `POST /api/v3/connected_accounts` ``
span.
## Context
Salvaged from the now-superseded #3518 — re-derived against the current
generator. The rest of #3518 (drift-gate workflow, regenerated MDX,
generator
rework) is obsoleted by the post-merge auto-regeneration workflow
(`generate-sdk-docs.yml`) and #3613.
## Summary
Auto-generated TypeScript SDK reference docs from
`ts/packages/core/src/`.
Regenerates pages at `docs/content/reference/sdk-reference/typescript/`
to reflect changes in the core package's public API (new methods,
updated signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Auto-generated Python SDK reference docs from `python/composio/`.
Regenerates pages at `docs/content/reference/sdk-reference/python/` to
reflect changes in the Python package's public API (new methods, updated
signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Updates the scoped project API key permissions reference with the routes
cataloged in ComposioHQ/platform#10638 (PLEN-2623):
- **Sessions** — now covers MCP server management (`/mcp/servers*`,
`/mcp/{id}`, instances), the MCP runtime transport, and the tool router
MCP transport
- **Tool execution** — adds `POST /files/upload/response` and `GET
/files/list` (file legs of tool execution)
- **Triggers** — adds the SDK/CLI realtime subscribe endpoints
(`triggers.subscribe()` / `composio triggers listen`)
Tables mirror `PROJECT_API_KEY_PERMISSION_CATALOG` as of the platform
merge.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Adds a migration guide for developers moving from **MCP servers**
(`composio.mcp.create` / `composio.mcp.generate`, the "Single Toolkit
MCP" flow) to **sessions**.
New page:
`docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx`
(registered in `migration-guide/meta.json` after `direct-to-sessions`).
### What it covers
- What carries over (tools, auth configs/connected accounts — no
re-auth, the MCP URL pattern, per-user isolation, fixed tool lists)
- Old → new mapping table + the *why*
- 3-step migration (`composio.create` replaces server+generate · point
the client at `session.mcp.url` · direct-tools preset for a fixed tool
list)
- Things to know: reuse one session, `session.tools()` as native
framework tools, `session.execute()` for tool execution without an LLM,
shared connections, tenant params, white-labeling, triggers, and a
pointer to **Composio For You** (connect.composio.dev) for
no-code/personal app connections
### Before merge
- [ ] Confirm cross-links resolve in preview
(`/docs/configuring-sessions`,
`/docs/authenticating-users/shared-connections`,
`/docs/white-labeling-authentication`, `/docs/how-composio-works`)
- [ ] Sanity-check the `session.execute` / `session.tools` /
direct-tools-preset snippets against the current SDK
- [ ] Confirm the `https://connect.composio.dev` link + product-switcher
wording for Composio For You
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Catalog additions from ComposioHQ/platform#10638 (PLEN-2623):
- sessions now covers MCP server management and both MCP transports
- tool execution adds files upload/response and files list
- triggers adds the SDK/CLI realtime subscribe endpoints
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
## Summary
- Add a Project API key permissions reference page under `Reference >
Authentication`.
- List the routes covered by each permission area and access level.
- Add stable anchor links for dashboard Learn more links, for example
`/reference/authentication/project-api-key-permissions#webhooks`.
- Link the new page from the Reference authentication overview and the
Projects page.
- Fix two existing docs build blockers that prevented local
preview/build: quote SDK reference frontmatter and use `zod/v3` in the
migration-guide custom tool sample.
## Validation
- `bun run lint:links`
- `bun run types:check`
- `bun run build`
- `curl -I
http://localhost:3000/reference/authentication/project-api-key-permissions`
returned `200` locally.
This PR is **part 3 of 3** splitting
https://github.com/ComposioHQ/composio/pull/3505 to make the removal of
the old 2025 custom tools easier to review. It carries the **docs**
slice.
- builds on top of https://github.com/ComposioHQ/composio/pull/3509
(stacked — this PR's base is `remove-ts-custom-tools`)
- deletes the legacy `/docs/tools-direct/custom-tools` page and prunes
its `meta.json` entry
- retargets redirects for `/docs/tools-direct/custom-tools` and the
`:path*` wildcard to `/docs/toolkits/custom-tools-and-toolkits`, with
matching `redirects.test.ts` expectations
- updates migration-guide, glossary, proxy-execute, and executing-tools
prose; fixes the `ctx.proxyExecute` example to include the required
GitHub toolkit
- updates agent guidance (`AGENTS.md`, `building-agents` skills) to the
experimental custom tools API
## Notes
- This slice is a byte-identical subset of #3505 — the three split
branches recombine to that PR's exact tree. Docs link/redirect checks
could not run in the source checkout (missing docs deps); CI runs them
per PR.
This PR is **part 2 of 3** splitting
https://github.com/ComposioHQ/composio/pull/3505 to make the removal of
the old 2025 custom tools easier to review. It carries the
**TypeScript** slice.
- builds on top of https://github.com/ComposioHQ/composio/pull/3508
(stacked — review/merge the Python slice first; this PR's base is
`remove-py-custom-tools`)
- removes the legacy `composio.tools.createCustomTool(...)` in-memory
registry: the plural `CustomTools` model, registry wiring, legacy-only
tests/examples/`ts/docs` pages, and stale error/type exports
- preserves the 2026 tool-router APIs: `experimental_createTool`,
`experimental_createToolkit`, `ToolRouter`, `ToolRouterSession`, and
inline custom-tool execution
- regenerates the TypeScript SDK reference so raw tool listing no longer
describes the removed local registry and points to session-scoped custom
tools
- adds a `@composio/core` minor changeset
## Notes
- The committed SDK reference is **verified self-consistent**: `pnpm
--filter @composio/core generate:docs` reproduces it with zero diff.
- This slice is a byte-identical subset of #3505 — the three split
branches recombine to that PR's exact tree. See #3505 for the original
verification logs (`typecheck`, `test`, `lint`, `cf-workers` e2e); CI
re-runs per PR.
Small follow-up to #3517 (merged). Adds a docs link to the **Workbench**
changelog item — the only outstanding ask from the review thread
(Karan/Palash):
> Code execution through the remote workbench … now runs only inside a
[Composio session](https://docs.composio.dev/docs/how-composio-works).
No other changes; the rest of the entry is as merged.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Adds one concise changelog entry:
`docs/content/changelog/06-04-26-security-reliability-hardening.mdx`.
Summarizes the post-incident wave of changes, link-forward (no
migration-guide links), matching the existing
`docs/content/changelog/*.mdx` format. Source of truth + rationale live
in Linear PRO-255 (Customer Comms).
### What it covers
- **Auth / API keys:** MCP auth required, cookie/session auth removed on
v3.1, non-recoverable keys, **scoped API keys** (Proxy Execute opt-in at
creation, off by default), auto-added IP allowlists, **MFA available for
Dashboard sign-in (off by default)**.
- **Connections:** managed-OAuth `initiate` → `link` (Jul 3 cutover),
token redaction across **managed + custom** auth configs, Proxy Execute
for provider actions.
- **Webhooks / Endpoints:** public-URL + signed deliveries;
`/api/rerouted/v1` and `/v2` retired (`410`).
- **Dashboard:** `platform.composio.dev` → `dashboard.composio.dev`
redirect, restoration-period `401`s (API/SDK stay functional), MCP
configs view removed (use the MCP API / move to Composio sessions).
### Before merge (reviewer checks)
- [ ] Confirm links resolve: Proxy Execute, Webhook Subscriptions API,
MCP API reference, Composio sessions.
- [ ] Re-confirm live state: MFA is opt-in (not required);
destructive-tool denylist was re-enabled.
- [ ] Confirm the per-project two-factor toggle is intentionally
excluded (distinct from Dashboard MFA).
- [ ] Confirm publish date (`2026-06-04`).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Rahul Tarak <cryogenicplanet@gmail.com>
## Summary
- **Dark/light theme switcher** in the navbar. Drops `forcedTheme:
'light'` so the toggle actually flips themes; sidebar footer toggle
stays disabled so there's only one switcher.
- **Dark mode color pass.** `--composio-brand` lifts to a muted
`#5B8BF0` (the deep `#0007cd` brand reads as unlit text on `#0f0f0f`).
Card / muted greys nudge to `#1c1c1c` / `#1f1f1f`. Borders drop from 10%
white to 6% so card edges sit back. `--border` / `--sidebar-border`
follow suit.
- **Square navbar.** Search input and the new theme toggle render with
`border-radius: 0` to match the rest of the navbar.
- **Welcome-page scroll reset.** New `ScrollReset` client component
wired into the root layout. Next.js App Router skips its built-in scroll
reset when the new route resolves to the same dynamic `page.tsx` segment
— every link from the welcome page to a `/docs/*` page hits this case,
so users were landing mid-page on the new route. Now `usePathname()`
change ⇒ `window.scrollTo(0, 0)` (skips first render and any
hash-bearing navigation).
- **`platform.composio.dev` → `dashboard.composio.dev`** across docs
content + the direct-execution LLM guardrail (28 files).
`docs/public/openapi*.json` left alone — auto-generated, and the
surviving reference is literally to the legacy dashboard.
## Test plan
- [ ] Toggle theme from the navbar; verify both light and dark render
- [ ] In dark mode, confirm "Docs" nav active state, chip icons,
"CONNECTED" labels, and Ask AI button read clearly against `#0f0f0f`
- [ ] Scroll to the bottom of `/docs`, click any link in HomeResources /
HomeSurfaces / HomeFeatures — the new page should land at scroll 0
- [ ] Click a TOC `#anchor` link inside a docs page — should still
scroll to the anchor (not get clobbered to 0)
- [ ] Spot-check a few rewritten URLs in cookbooks / quickstart — all
`platform.composio.dev` should now be `dashboard.composio.dev`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
Reworks the docs welcome page (`/docs`) into a two-column hero with an
animated agent chat mock + tool overlay, plus four restructured homepage
sections.
### Hero (`DocsHeroV2`)
- Left: headline (`Start building with Composio.`), short sub,
brand-blue chip column (Quickstart, API reference, Toolkits).
- Right (lg+ only): mock chat panel with the v1 hero's per-agent skin
(`Claude Cowork` / `ChatGPT Codex` / `Your AI Agent`), step-by-step
timeline-driven animation (user prompt → thinking dots → tool-trail
items → assistant response), and a floating "active tool" card layered
over the chat's left edge.
- L-shape SVG connector between chat and overlay: muted grey resting
state + brand-blue glow + bright line that re-draw via `pathLength` on
every tool change.
- Mock chat hidden below lg.
### Homepage sections
- **`HomeFeatures`** — `Everything you need to ship production agents.`
2×2 grid with bespoke visuals per pillar: 8×2 toolkit grid with `+1K`
cell, sessions panel (`USER_ID` + connected apps), triggers feed (`LIVE`
indicator + recent events), and a workbench mock with animated 4×2 CPU
lights. `auto-rows-fr` on `sm:` so cards equalize on tablet/desktop but
breathe on mobile.
- **`HomeSurfaces`** — `Three ways to use Composio.` bento: Developer
card spans full width (`md:col-span-3`) and shows 8 provider logos
(Anthropic, OpenAI, Vercel AI, Google, LangChain, CrewAI, LlamaIndex,
Mastra). Row 2: For You (with Claude / Codex / Cursor / Windsurf /
OpenClaw client logos), CLI (with `curl ... | bash` install snippet and
functional copy button), Agents.
- **`HomeResources`** — `Reach for the rest.` six-card footer row with
Quickstart, API reference, Cookbooks, Changelog, Toolkits,
Troubleshooting.
### Other
- Ports the landing-page hero into `components/landing-hero/` (kept
under the original `DocsHero` for easy revert; commented out, V2 wired
in).
- Theme-aware `--hero-*` CSS vars for chat-skin colors so the chat reads
in both light and dark.
- Removes the old `Works with your stack` provider grid (the providers
now live inside the Developer surface card).
## Test plan
- [ ] Verify hero animation cycles through 3 examples on desktop
- [ ] Verify L-shape connector pulses in brand blue on every tool change
- [ ] Verify chat mock is hidden on mobile and left column reads on its
own
- [ ] Verify dark mode (chat skins, connector, card surfaces, code
blocks)
- [ ] Verify CLI install copy button copies and toggles the icon to ✓
- [ ] Verify all chip / card hrefs resolve
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
- Rework the CLI docs around Composio for You / Claude Code usage, with
sections for knowledge work, `run`/sub-agents, trigger listening,
developer workflows, and unsupported direct CLI embedding.
- Move CLI into the top of Other topics and remove single-toolkit MCP
from the Docs sidebar.
- Move Changelog into Reference after Errors, with a grouped single-page
changelog, scroll-based date anchors, and redirects from old
`/docs/changelog` URLs.
- Add the Claude logo to the “Open in Claude” page action.
## Tests
- `cd docs && bun run lint:links`
- `cd docs && bun test tests/static/navigation.test.ts`
- `cd docs && bun run build`
## Summary
- Stack this PR on top of #3455 (`docs/love-fixes`).
- Rework the former Core Concepts / Getting Started / Guides / Features
area into a smaller set of sections:
- Build with sessions
- Authenticate users
- Triggers and webhooks
- Direct Tool Execution Guides (Legacy)
- Other topics
- Move conceptual session pages (`how-composio-works`, users/sessions,
tools/toolkits, authentication, workbench, triggers) into the
appropriate grouped sections.
- Merge duplicated custom-auth content into `Managed vs custom auth`
(`/docs/custom-app-vs-managed-app`) and redirect the old
`/docs/using-custom-auth-configuration` URL.
- Trim repeated OAuth-app setup from white-labeling docs so that page
focuses on branding, callback-domain routing, and post-auth redirect UX.
- Clean up “What to read next” cards so non-legacy pages no longer point
at direct-execution docs and first point to the next item in their
section where possible.
- Fix the session lifecycle contradiction in `how-composio-works` so it
matches the current persisted/reusable session model.
## Checks
- `cd docs && bun run lint:links`
- `cd docs && bun test tests/static/navigation.test.ts`
## Summary
Three small docs polishes:
- **Hide the disgusting "Ask AI" side tab.** The Decimal widget renders
its own `.decimal-widget-sidebar-tab` launcher (vertical pill with
sideways text) on every page. We already trigger the widget from our own
"Ask AI" button in the nav, so the third-party launcher is redundant
*and* ugly. Hidden via CSS in `app/global.css`.
- **Fix the Playground nav link.** It pointed at
`platform.composio.dev/auth?next_page=/tool-router` — which (a) hits a
dead host now that platform has moved to `dashboard.composio.dev`, and
(b) lost the playground's connect check on the redirect. Repointed to
`https://dashboard.composio.dev/~/project/playground`, which is the
dashboard's smart-resolver route: it handles login (`?next=`), looks up
`last_visited` / default org+project, and lands the user on
`/{org}/{project}/playground` with the connect step intact. Same fix
applied to the toolkits landing CTA and the welcome-page Playground
card.
- **Trim the welcome page.** Dropped the duplicated intro Cards row, the
"Get Started" / "Explore" / "Features" / "Community" headers, and the
secondary Features grid. Now it's: intro → AIToolsBanner → Quickstart →
Toolkits + Playground → Providers. Much cleaner.
## Test plan
- [ ] `bun run scripts/validate-links.ts` passes (already verified
locally — 0 errors)
- [ ] On preview deploy, the side "Ask AI" tab is gone
- [ ] Clicking "Playground" in the nav (logged out) lands on login →
playground; (logged in) lands on `/{org}/{project}/playground`
- [ ] Welcome page renders without missing-icon errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
New documentation page at `/docs/auth-configuration/shared-connections`
covering the `accountType` and per-user ACL surface added to
`@composio/core@0.9.1` and `composio==0.14.0`.
## What's covered
- **SHARED vs PRIVATE** — comparison table; what each means for who can
use the connection and how it's resolved
- **Creating a SHARED connection** — `link()` with `accountType:
'SHARED'` and an initial ACL
- **ACL resolution rule** — 4-step deny-wins ordering + a *"common
patterns"* table (only-creator, allow-all, targeted-allow,
everyone-except-N, combined)
- **Updating the ACL** — `updateAcl()` with PATCH semantics, plus an
explicit footgun warning about `notAllowedUserIds: []` clearing the deny
list
- **Using a shared connection** — pinning into a tool-router session via
`connectedAccounts`, or direct execute via `connectedAccountId`
- **Inspecting the ACL** — `get()` returns `accountType` +
`aclConfigForShared`; the latter is `undefined` when the caller isn't
authorised to see it
- **Error handling** — table mapping `ComposioAclOnlyForSharedError`,
`ComposioSharedAccessDeniedError`, and
`ComposioSharedConnectionNotAccessibleError` to their trigger
conditions, with try/except examples
## Other changes
- **`docs/package.json`**: bump `@composio/core` from `^0.9.0` to
`^0.9.1`. The published `0.9.1` is what carries the new typed surface;
without this bump, twoslash type-checks against `0.9.0` and the new
fields show as unknown properties.
- **`docs/content/docs/auth-configuration/meta.json`**: insert
`shared-connections` into the Authentication sidebar between
`connected-accounts` and `migrating-initiate-to-link`.
## Sanitization
Followed the same scrub conventions the SDK PRs landed on:
- No Hermes / Apollo PR references
- No internal backend error code names
- No JSONB / storage-layer details
- No *"project member"* wording (users don't belong to a project
entity); used `userId` and the pinning mechanism instead
- *"API key caller"* instead of *"project/org API key"*
## Test plan
- [x] `bun run build` — 1411 pages generated, no twoslash errors against
the published `@composio/core@0.9.1`
- [x] Manual link audit — `/docs/configuring-sessions`,
`/docs/managing-multiple-connected-accounts`,
`/docs/auth-configuration/connected-accounts`, and the internal
`#using-a-shared-connection` anchor all resolve
- [ ] Preview deploy spot-check — confirm the Cards icons (`Database`,
`Plug`, `Wrench`) render and the sidebar shows the new entry under
Authentication
🤖 Generated with [Claude Code](https://claude.com/claude-code)
The page was sitting under Direct Tool Execution Guides → Authentication.
Shared Connections is a connection-creation feature, not a direct-tool
workflow, so it slots better under Getting Started → Authenticating
users alongside `in-chat-authentication` and `manually-authenticating`.
Changes:
- `git mv docs/content/docs/auth-configuration/shared-connections.mdx
docs/content/docs/authenticating-users/shared-connections.mdx`
- Removed `shared-connections` entry from
`auth-configuration/meta.json`.
- Appended `shared-connections` to `authenticating-users/meta.json`.
- Doc body unchanged. The internal link to
`/docs/auth-configuration/connected-accounts` in "What to read next"
still resolves (the connected-accounts page stays under
auth-configuration).
New URL: `/docs/authenticating-users/shared-connections`.
Verified: `bun run build` clean, `bun run scripts/validate-links.ts`
clean (0 errors).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two prose tweaks so TypeScript readers don't have to mentally translate
from Python-style field names:
- "Creating a SHARED connection" intro now mentions both
(`accountType` in TypeScript, `account_type` in Python).
- "Common ACL patterns" caption notes the table uses camelCase and tells
Python callers what to translate to.
Pure prose change — no code samples touched. Build clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three updates after the post-review changes on the SDK PRs:
1. **TS `updateAcl` shape** — the review feedback on PR #3424 moved the
call from a top-level `experimental_updateAcl(composio, id, opts)`
export to a method on the `composio.experimental` namespace, mirroring
Python (`composio.experimental.update_acl(id, ...)`). All TS code
samples now call `composio.experimental.updateAcl(id, opts)`. The
stale `experimental_updateAcl` import is dropped from the
error-handling sample too.
2. **Top callout** — no longer mentions the discarded top-level export;
reads as "the SDK methods live under the `composio.experimental`
namespace" with both language names.
3. **Listing SHARED connections** — new section before "Inspecting the
ACL". Shows the `account_type` (Py) / `accountType` (TS) filter that
was missing from the doc. The wire keeps this flat as a query param
(unlike the nested experimental block on create/update), so the SDK
surface stays flat too — table of `PRIVATE` / `SHARED` / `ALL` and
tabbed Python + TS examples scoping by user.
Build: `bun run build` clean.
TS blocks still carry `// @noErrors` because `@composio/core` on npm
doesn't yet expose `composio.experimental.updateAcl` or the typed
`accountType` filter — both ship in PR #3424. Those directives come
out in a follow-up doc commit once the SDK publishes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
# Description
Adds a customer-facing changelog entry announcing the new `POST
/api/v3.1/connected_accounts/{nanoid}/revoke` endpoint.
The entry covers:
- The endpoint shape, an example request, and an example `200 OK`
response (with the `revoked_tokens` array reflecting which token
subjects were killed at the provider on this call)
- Full status code table (`200` / `400` / `404` / `409` / `500`)
- **Revoke-then-delete semantics**: deleting a connected account does
NOT currently cascade to upstream revoke — customers should call
`/revoke` first if they need credentials killed at the provider. A
future release may cascade automatically; we'll announce separately
- **Best-effort behavior**: some providers don't expose revoke for one
or both token subjects; customers should always read `revoked_tokens`
rather than assume both were revoked
- **Externally revoked tokens**: if a user revokes via the provider's
UI, the revoke call may fail — such connections are eventually marked
`EXPIRED` by the platform
Endpoint path and response shape verified against
`apps/apollo/src/pages/api/v3.1/connected_accounts/[nanoId]/revoke.ts`
in hermes.
Follows `docs/.claude/guides/changelog.md` conventions (filename
`MM-DD-YY-suffix.mdx`, frontmatter with `title` + `date` +
`description`, sections start at `###`, no top-level `#`, no emojis).
> Note: SDK / public OpenAPI visibility for this endpoint is being added
in parallel in hermes — by the time this entry publishes, the endpoint
will be reachable from `backend.composio.dev` for customer projects.
# How did I test this PR
- Verified file location, filename pattern, and frontmatter against
`docs/.claude/guides/changelog.md` and a recent peer entry
(`12-30-25-proxy-binary-data.mdx`)
- Cross-checked the documented request path, response schema, and status
codes against
`apps/apollo/src/pages/api/v3.1/connected_accounts/[nanoId]/revoke.ts`
(route definition, `RevokeConnectedAccountResponseSchema`, declared
response codes)
- The repo's Fumadocs build (`bun run build`) validates MDX and will
catch any syntax / link issues in CI
The previous samples called the flat-field surface that `@composio/core@0.9.1`
and `composio==0.14.0` shipped. The wire is being restructured by
hermes#9960 to nest those fields under an `experimental` block, and the
follow-up SDK PRs will move the call sites to a matching `experimental`
namespace (mirroring the custom-tools precedent of `experimental_createTool`
/ `composio.experimental.tool`). This commit updates every code sample to
the post-restructure shape so the doc is internally consistent with the
experimental rollout it advertises in the top callout.
Specific changes:
- `link()`: `experimental: { accountType, aclConfigForShared }` (TS) /
`experimental={"account_type": ..., "acl_config_for_shared": ...}` (Py).
- `updateAcl()` → `experimental_updateAcl(client, id, opts)` (TS top-level
export, mirrors `experimental_createTool`) / `composio.experimental.update_acl(id, ...)`
(Py, mirrors `composio.experimental.tool`).
- Retrieve response inspection now reads from `account.experimental?.accountType`
/ `account.experimental?.aclConfigForShared` to match the response shape.
- Error-handling examples use the experimental method names too.
- Common ACL patterns table clarifies the inner shape is wrapped inside the
`experimental` block at the call site.
- Top callout updated to call out the namespace move so readers know what
they're looking at.
TypeScript blocks that target the post-restructure surface carry
`// @noErrors` because the published `@composio/core@0.9.1` doesn't yet
expose `experimental_updateAcl` or the nested `experimental` options on
`link()`. The directives will come out in a follow-up docs PR once the
SDK PRs publish.
Pinning a SHARED connection in a session (`connectedAccounts: { gmail: [...] }`)
and direct execute (`composio.tools.execute(slug, { connectedAccountId })`)
stay unchanged — session config and execute aren't part of the experimental
wire restructure.
Verified: bun run build clean (1411 pages, no twoslash errors with @noErrors).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors the convention used by `Custom Tools and Toolkits (Experimental)`:
- Title becomes `Shared Connections (Experimental)` so the experimental
status is visible in the sidebar entry and at the top of the page.
- Adds a `<Callout type="warn">` immediately under the frontmatter with
the same wording style custom-tools uses, plus a forward-looking note
that the SDK surface is being restructured under a
`composio.experimental.*` namespace so callers know to expect future
migration.
Code samples stay on the currently-published SDK shape (flat
`accountType` / `aclConfigForShared` args on `link()`, `updateAcl()`,
`authorize()` — what `@composio/core@0.9.1` and `composio==0.14.0` ship
today) so twoslash continues to typecheck. A follow-up docs PR will
update them to the experimental-namespace shape once those SDK PRs
publish.
Verified: bun run build clean (1411 pages, no twoslash errors).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Reword 400 row: "Revoke is not supported for this toolkit"
- Simplify 404 row to "Connected account does not exist"
- Drop "Database failure" wording from 500 row
- Drop "(Today)" qualifier and the future-cascade speculation paragraph
- Drop the auto-EXPIRED platform-detection claim (not true for non-OAuth2
or OAuth2 without refresh tokens)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: sarthak <sarthak@composio.dev>
The May 8 changelog ("Session reuse, update, and connected accounts as
arrays") lists @composio/core ≥ 0.10.0 as the minimum version for the
composio.use() / session.update() / connectedAccounts-array changes, but
the latest published version on npm is 0.9.1 and the .create()/.use()
methods plus the array-shape connectedAccounts field are both present in
its public type surface (verified by extracting the published 0.9.1
tarball and grepping dist/*.d.cts). 0.10.0 does not exist on npm.
The adjacent May 7 changelog ("preload + direct tools preset") already
lists @composio/core ≥ 0.9.0, which is consistent with 0.9.1 being the
shipped version.
Co-authored-by: dhawal <dhawal@composio.dev>
Add a customer-facing changelog entry for the new
POST /api/v3.1/connected_accounts/{nanoid}/revoke endpoint, documenting
revoke-then-delete semantics, best-effort behavior, and how externally
revoked connections are handled.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: sarthak <sarthak@composio.dev>
New page at /docs/auth-configuration/shared-connections covers the
account_type and per-user ACL surface added to the Connected Accounts
SDK in 0.9.1:
- When to use SHARED vs PRIVATE (table)
- Creating a SHARED connection via link() with an initial ACL
- The 4-step deny-wins resolution rule + common ACL patterns
- updateAcl() with PATCH semantics + empty-array footgun warning
- Using a shared connection from a tool-router session (pinning) or
via direct execute with connectedAccountId
- Inspecting account_type + aclConfigForShared on get() responses
- Error handling table covering ComposioAclOnlyForSharedError,
ComposioSharedAccessDeniedError, ComposioSharedConnectionNotAccessibleError
Other changes:
- Bump docs/package.json @composio/core dependency from ^0.9.0 to ^0.9.1
so twoslash type-checks against the version that exposes the new
fields.
- Wire the new page into the Authentication sidebar between
connected-accounts and migrating-initiate-to-link.
Verified: bun run build clean (1411 pages including the new one).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.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>
The /reference/api-reference/webhooks page lists both Subscriptions and Endpoints operations on one page, so the generic page-level link was ambiguous about which API the prose was referring to. Each label now points to its create operation page (postWebhookSubscriptions / postWebhookEndpoints).
Also moves the Webhook Endpoints API pointer up out of Step 2 into the section intro so it scopes the whole walkthrough.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Single Webhook Endpoints API pointer at Step 2 of creating-triggers, mirroring the Subscriptions API pointer pattern; same pointer added to the Webhook Endpoint glossary entry.
- Reword Slack-walkthrough intro to direct readers to per-toolkit FAQ (Slack, Notion).
- Add "How do I set up the Notion webhook ingress endpoint?" FAQ covering the reverse-direction verification flow (token from Composio pasted back into Notion).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The TypeScript samples in the changelog and provider docs declared the
rehydrated session as `session2`, which is misleading — it's the same
logical session, just being recreated from a stored ID. Rename to
`session` to match the Python samples and add `// @noErrors` so twoslash
ignores the redeclaration (these blocks are illustrative, not runnable).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: abir <abir@composio.dev>
Each code example now shows how to store the session ID and reuse it
with composio.use() instead of calling create() again, as commented
code below the create call.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Alberto Schiabel