docs agent hallucinated api endpoints, generated broken links
Fixes generated docs where a docs agent invented API endpoints, producing broken links. Use when reference docs link to endpoints that do not exist in the API, or link checkers report 404s on agent-generated endpoint URLs. Key trigger: endpoint links in generated docs 404 or match no real route.
TL;DR
Verify every endpoint the agent documents against the real route surface (your OpenAPI spec paths or the framework's route list) and run a link checker over the built docs before publishing. The agent linked endpoints it imagined because no step compared its output to the actual API. Route-checking turns invented endpoints into caught errors.
docs agent hallucinated api endpoints, generated broken linksSteps
- Extract the endpoints from the generated docs: search the built pages or sources for path-like links (strings starting with /v1/, /api/, and similar in your project). Expected: a concrete list of documented endpoints.
- Pull the real route list: from your OpenAPI spec's paths object, or your framework's route listing command. Expected: the authoritative set of endpoints that actually exist.
- Diff the two lists: every documented endpoint must exist in the real routes. Expected: a concrete list of invented endpoints (in docs, not in routes).
- Delete or correct the invented endpoints, fix the links, and rebuild. Expected: a link checker over the built site reports zero broken internal endpoint links.
- Add the gate: the agent diffs documented endpoints against the route list before publishing, and any invented endpoint fails the run. Expected: a test run with a fake endpoint exits nonzero naming it.
Use this when
- generated docs link to endpoints that 404
- a link checker flags agent-generated endpoint URLs
- API reference was written by an agent, not a human
Not for this skill when
- endpoints are real but documented wrongly (content issue)
- links break because the API changed after publishing (drift; regenerate)
- humans wrote the docs (review problem)
Variant phrasings
- agent invented api endpoints in docs
- generated docs link to nonexistent endpoints
- broken endpoint links from docs agent
Why it happens
Endpoint paths are highly patterned, so a language model can extend the pattern into endpoints that look right but were never implemented. The docs read convincingly, the links resolve nowhere, and users discover it in production.
Edge cases
- Path parameters make naive string matching fail: compare route patterns, not literal URLs with sample ids.
- Versioned prefixes are a classic mismatch: check the version segment explicitly.
- Endpoints behind feature flags exist in code but not in prod: decide whether docs should list them at all.
- External links rot independently of hallucination: check those on a schedule too.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstr8chTxbNWKTKW8kEtf3Xw