fix: repair Chainhooks API reference by vendoring its OpenAPI spec

[rafa-stacks]

What & why

The Chainhooks API reference pages (e.g. /apis/chainhooks-api/reference/chainhooks/register-chainhook) render broken. The build fetched the chainhook OpenAPI spec from https://chainhooks-api.vercel.app/openapi.json, but that deployment is gone. The fetch failed, so openapi/chainhook-api.json was never produced and every <APIPage> in the chainhooks reference had no document to render.

The legitimate spec lives in a private repo, so it can't be fetched at build time like the other (public) specs.

Changes

• Vendored the spec at scripts/vendored-specs/chainhook-api.json (bundled/dereferenced from the private repo's openapi.yaml), tracked in git.
• scripts/fetch-openapi-specs.mts — removed the dead chainhooks-api.vercel.app URL from API_SPECS, and added a VENDORED_SPECS list + copyVendoredSpec() step that copies each vendored spec into openapi/<name>-api.json during generate, before markdown generation. openapi/ stays fully gitignored (purely generated).

Verification

• bun run generate succeeds with no chainhook fetch error; copies the spec into place and produces the 12 chainhook markdown files.
• The previously-broken register-chainhook page (and get/delete/evaluate/secrets/status) render at 200 with the correct POST /me/ operation, cURL example, request body, and 200 response schema.
• openapi/ remains gitignored; only scripts/vendored-specs/chainhook-api.json is tracked.

Notes for reviewers

• Security: the chainhooks-api.vercel.app deployment has been claimed by a third party (bug-bounty POC). Removing our dependency closes the docs exposure, but the takeover itself should be reported/reclaimed internally.
• Maintenance: because the source repo is private, the vendored JSON does not auto-update — regenerate scripts/vendored-specs/chainhook-api.json from stx-labs/chainhooks packages/api/openapi.yaml when the API changes. A longer-term option is publishing that spec to a public URL and repointing the fetch script.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hiro-systems-docs	Ready	Preview	Jul 31, 2026 7:41pm