This PR:
- fixes a regression introduced by
https://github.com/ComposioHQ/composio/pull/3956: fumadocs-openapi 11's
`groupBy: 'tag'` silently skips operations whose tag is not declared in
the document's top-level `tags` array, which 404'd all 16 Projects and
Organization Management operation pages (e.g.
`/reference/api-reference/projects/postProjectUsageSummary`) on both
v3.1 and v3, and dropped them from the sitemap and search index
- adds `declareOperationTags()` (`docs/lib/openapi-tags.ts`), applied at
spec load time in `lib/openapi.ts` (covers build-time-fetched specs) and
at sync time in `scripts/fetch-openapi.mjs`, which now also warns when
the upstream payload omits tags; the checked-in specs are normalized
accordingly (purely additive)
- adds CI guards in `tests/static/api-reference-routes.test.ts`: spec
invariants (every visible operation has a tag and `operationId`),
bidirectional spec-vs-generated-routes set equality through the
production loader path, a negative test pinning fumadocs' silent-drop
behavior (fails when upstream fixes it, signaling the workaround can be
retired), and validation that every `ApiEndpointsTable` quick-link href
resolves to a generated page
- extends `Docs - Check Links` with a nightly (02:30 UTC) + manual
external-URL sweep via a new `lint:links:external` script; the validator
only fails on evidence a link is dead (404/410 or repeated network
errors, with UA/timeout/GET-fallback/retry and per-URL caching) and
scheduled failures file a deduplicated tracking issue; PR runs keep the
fast internal-only check
- fixes six dead external links the first sweep found (moved Claude
Agent SDK docs, stale dashboard settings URL ×2, a `master`-branch path
now pinned to tag `0.5.0+post.1`, and two removed `ComposioHQ` example
repos whose mentions were dropped — their code is embedded in the pages
via `RepoBrowser`)
## Context
fumadocs-openapi 10 generated a page for any tag string found on an
operation; v11 requires the tag to be declared top-level and skips
silently otherwise (`preset-auto.js`: `builder.fromTagName(tag)` →
`continue`, no warning). The backend spec generator omits `Projects`,
`Organization Management`, and `Invite Codes` from `tags`, so their
operation pages vanished while the checked-in MDX tag landing pages kept
rendering with dead quick links. With the normalizer, the generated URL
set is byte-identical to the pre-#3956 set (234 routes, verified via
`getReferenceSource().getPages()` diff); no revert needed.
Existing checks missed this because `lint:links` only extracts markdown
links and `Card` hrefs (the dead links live in `ApiEndpointsTable`'s
array prop) and validates against the same loader that shrank, and the
integration suite samples fixed routes under tags that survived. The new
completeness guard derives expectations from the specs themselves, so
routine data syncs don't churn it.
## 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>
## What was wrong
The API reference docs were shipping staging URLs to users. There were
two separate leaks, both from the same source: the scheduled
`docs-update-data` workflow fetches the OpenAPI specs and toolkit data
from staging every 5 hours and auto-commits them.
The first leak was the curl base URL. `servers[0].url` in `openapi.json`
and `openapi-v3.json` rendered as `http://staging-apollo.composio.dev`
in every curl example. That is what
https://github.com/ComposioHQ/composio/pull/3761 tried to fix.
The second leak was in the toolkit data. `toolkits.json` carried 269
`https://staging-backend.composio.dev/api/v1/auth-apps/add` default
values, surfaced in the white-labeling and auth-config docs. #3761 never
touched this file.
## Which PR caused it
Karan asked on Slack whether we could pin down the PR that introduced
this. We can. It was https://github.com/ComposioHQ/composio/pull/3426
(commit `a3e58a421`, merged 2026-07-03), which flipped `servers[0].url`
from `https://backend.composio.dev` / `PRODUCTION API` to
`http://staging-apollo.composio.dev` / `STAGING API` in both specs.
It was not a hand-written change. #3426 is itself an auto-generated PR
from this same `docs-update-data` workflow, opened by
`github-actions[bot]` on the `docs/auto-update-data` branch. The
workflow fetched from staging, staging serves the staging server URL in
its spec, and the value landed in the committed files where nobody
caught it inside a large auto-generated diff. That is the reason the
real fix belongs in the generator and the workflow, not in a one-off
edit to the JSON.
## Why #3761 was not enough
#3761 pinned `spec.servers` to production inside `fetch-openapi.mjs`.
That closed the first leak, but three things stayed open.
It only covered the OpenAPI specs. The 269 staging hosts in
`toolkits.json` come from a different generator, `generate-toolkits.ts`,
and stayed live on the docs site.
It added no CI guard. The fix was a single line in a generator with
nothing asserting it. A later refactor that dropped or reordered that
line would republish staging on the next 5-hour regeneration, which is
precisely the recurring failure that produced the original report.
And it scrubbed the symptom rather than the source. The workflow kept
fetching from staging; the pin just rewrote one field afterward.
## The fix
I addressed it at four layers, so no single regression brings staging
back.
**Source.** `docs-update-data.yml` no longer overrides the base URL to
staging. The generators default to production, so the docs reflect
production.
**Generators.** The production URL now lives in one place,
`docs/scripts/production-api.mjs`. The toolkit and meta-tools generators
sanitize any staging host to production before writing, so a staging
fetch can no longer republish staging.
**Committed data.** I rewrote the 269 staging hosts already in
`toolkits.json` to production.
**Guard.** `docs/tests/static/production-urls.test.ts` asserts the
OpenAPI `servers` is production and scans both specs and every
`public/data/*.json` for any `staging-*.composio.dev` host. It is an
independent oracle: it hardcodes the expected value and deliberately
does not import the generator constants, so a wrong edit there fails CI
instead of moving both sides together. I verified it catches both the
original `staging-apollo` and the `staging-backend` leaks.
## One thing to confirm before merge
`COMPOSIO_API_KEY` is paired with `COMPOSIO_BASE_URL_STAGING` in every
other workflow, so it is most likely a staging key. If that is the case,
provision a production-capable key before the next scheduled run.
Otherwise that run fails on auth, which is loud and safe, rather than
silently republishing staging. The generator sanitizer and the guard
keep the output correct regardless of which environment the fetch hits,
so there is no risk in the interim.
## Testing
- `bun test tests/static/` passes 21 of 21 (16 existing, 5 new).
- The shared module loads and all three generators build under bun.
- No `staging-*.composio.dev` host remains under `docs/public/`.
- `docs-update-data.yml` re-validated as valid YAML.
# Description
The curl examples in the API reference docs pointed at **staging**
instead of production.
Reported (Slack): *"Curl in API reference docs points to staging-apollo
instead of backend.composio.dev."*
**Root cause:** the API reference (fumadocs, `docs/lib/openapi.ts`)
renders curl snippets using `servers[0].url` from the committed specs
`docs/public/openapi.json` (v3.1) and `docs/public/openapi-v3.json`
(v3.0). Both had:
```json
"servers": [{ "url": "http://staging-apollo.composio.dev", "description": "STAGING API" }]
```
This is a **recurring** regression, not a one-off stale file. The
scheduled workflow **`.github/workflows/docs-update-data.yml`** (`cron:
'0 */5 * * *'`, plus on Apollo production deploys) deliberately points
`OPENAPI_SPEC_URL` at **staging** (`COMPOSIO_BASE_URL_STAGING`, with a
guard that *fails* if it's production), runs `bun run
scripts/fetch-openapi.mjs`, and auto-commits the regenerated specs via
PR. Staging's spec serves `servers[0].url =
http://staging-apollo.composio.dev` (verified: `GET
https://staging-backend.composio.dev/api/v3{,.1}/openapi.json`), and
`fetch-openapi.mjs` did not override `servers` — so every ~5h the
staging server URL got re-committed (the most recent spec commit
`a3e58a421 docs: update ... API spec ...` came from exactly this
workflow).
The live production backend and the platform-committed apollo spec both
correctly serve `https://backend.composio.dev / PRODUCTION API`.
**Changes:**
- `docs/public/openapi.json` + `docs/public/openapi-v3.json`: set
`servers[0]` to `https://backend.composio.dev` / `PRODUCTION API`.
- `docs/scripts/fetch-openapi.mjs`: pin `spec.servers` to the production
URL in `postProcessSpec`. This is the **durable** fix — because the
update-data workflow fetches from staging, a JSON-only edit would be
reverted within ~5h; pinning in the generator forces the published curl
base URL to production regardless of which environment the source spec
was fetched from.
# How did I test this PR
- **Verified the servers value** in both committed specs (valid JSON):
- `node -e "require('./public/openapi.json').servers"` →
`[{"url":"https://backend.composio.dev","description":"PRODUCTION
API"}]`
- same for `public/openapi-v3.json`
- **Zero residual** `staging-apollo` references under `docs/public`,
`docs/scripts`, `docs/lib`.
- **Confirmed the recurrence mechanism:** read `docs-update-data.yml`
(staging fetch + auto-PR) and confirmed
`staging-backend.composio.dev/api/v3{,.1}/openapi.json` returns
`http://staging-apollo.composio.dev`, while live prod +
`apps/apollo/openapi.json` return `https://backend.composio.dev`. The
`postProcessSpec` pin overrides this in the generator.
- **Generator:** `node --check docs/scripts/fetch-openapi.mjs` → syntax
OK.
- **Docs static tests** (the "Docs - Tests" CI check): `bun test
tests/static/` → 16 pass, 0 fail.
- **CI on this commit:** Docs - Tests ✓, Docs - TypeScript Code
Validation ✓, Docs - Check Links ✓, Secrets Detection ✓, Vercel preview
✓.
- **Codex review:** no correctness issues found.
# Security
- **Trivy** (`fs --scanners vuln,secret --severity CRITICAL,HIGH,MEDIUM
--ignore-unfixed`) on all three changed files → clean (no
vulnerabilities, no secrets).
- **Socket** (dependency/supply-chain): N/A — no dependency or lockfile
changes.
- Note: `security/snyk (Composio)` shows failing, but it's a
**pre-existing repo-wide failure** (errors identically on PRs
#3756–#3761; this change touches no dependencies).
Triggered by: palash@composio.dev | Source: slack
Session: https://zen.corp.composio.io/dashboard/#/chat/zen-e559fb27fb16
Co-authored-by: Zen Agent <zen@composio.dev>
Co-authored-by: palash <palash@composio.dev>
- 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>
The OpenAPI spec now uses `x-internal` as a tag on internal endpoints.
Instead of maintaining a hardcoded list of paths to ignore, filter any
operation tagged with `x-internal` automatically.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The backend API spec contains anyOf/oneOf with many object variants
(e.g., connection_data with 68 variants, custom_connection_data with 10).
This caused fumadocs-openapi to render them as "object | object | object..."
This fix:
- Merges similar object schemas into a single object
- Combines enum values from all variants (e.g., authScheme now shows all 10 auth types)
- Recursively merges nested properties
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace the regex-based fix with a recursive solution that properly handles
all cases of invalid OpenAPI 3.0 schemas with "nullable: true" but no type.
The fix now:
- For additionalProperties: removes nullable (allows any type)
- For schemas with object examples: infers type: object
- For schemas with array examples: infers type: array
- For all other cases: defaults to type: object
This fixes 448 invalid schemas that caused fumadocs to crash when rendering
API reference pages like /tools/postToolsExecuteProxy.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The backend API spec has ~394 instances of `additionalProperties: { nullable: true }`
which is invalid OpenAPI 3.0 - `nullable` requires a `type` field.
This causes fumadocs-openapi to error: "nullable cannot be used without type"
Fix: Transform these to `additionalProperties: {}` (any type allowed) during fetch.
Note: The proper fix is in the backend API spec generation.
See: https://swagger.io/docs/specification/v3_0/data-models/data-types/
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add /api/v3/labs/tool_router/session to IGNORED_PATHS
- Remove CookieAuth from securitySchemes
- Remove CookieAuth from all endpoint security arrays
- Mirrors filtering done in fern/apis/openapi-overrides.yml
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Alberto Schiabel