## TL;DR
Delete the dead endpoint from the API reference source (or regenerate the reference from the live spec) and republish. Clients copy the documented path, get a 404, and file bugs against your API. Confirm the route is really gone from the server first, then remove every doc mention of it.

## The error
```text
api reference lists endpoint that no longer exists, clients get 404 error
```

## Steps
1. Confirm the route is gone: check the server's route table or the OpenAPI spec for the path. Expected: the path is absent from both, so the 404 is real and the docs are wrong.
2. Find every doc mention: `grep -rn "/v1/legacy-search" docs/` (use the actual dead path). Expected: a list of files and line numbers to fix.
3. Remove the endpoint section, or replace it with a short "Removed in v2.0 - use /v1/search" notice if users may still have it bookmarked. Expected: no full documentation remains for a dead route.
4. Rebuild the docs site. Expected: the build exits 0.
5. Search the built output for the dead path to confirm it is gone. Expected: zero hits in the built HTML.
6. Add a CI check that diffs documented paths against the OpenAPI spec so the next removal is caught automatically.

## Use this when
- Docs describe an endpoint that returns 404.
- An endpoint was removed in code but its docs page still exists.
- Client bug reports trace back to a documented route that no longer works.

## Not for this skill when
- The endpoint exists but returns 404 for bad input - that is API behavior, not docs drift.
- The docs are correct and the server deployment is behind - fix the deploy, not the docs.
- You are intentionally documenting a deprecated-but-live endpoint.

## Variant phrasings
### docs show endpoint that returns 404
Same drift, found by a user. Same fix.
### removed api endpoint still documented
Same. Delete or annotate the section.
### stale endpoint in api reference
Same family; "stale" here means the route is gone, not just changed.

## Why it happens
Endpoint removals ship in code PRs while the docs live in a separate directory or repo, so nothing forces the two to change together. Generated references avoid this only when the generation actually runs on every change. A checked-in generated file that nobody regenerates drifts the same way.

## Edge cases
- Versioned docs: the endpoint may be legitimately documented under v1 docs while removed in v2. Fix the version switcher and cross-links rather than deleting history.
- Redirects: if the old path now redirects, document the redirect target instead of deleting the page, so old bookmarks land somewhere useful.
- Search indexes: the built site search can keep surfacing the deleted page from a stale index. Rebuild the search index with the docs.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-XJsSpQx9SSc5PqSgXhRyQ