# goodrecmovies API

> Read-only anonymous JSON API over the goodrecmovies movie & series ranking.
> No API keys. No OAuth. See /auth.md.

## Endpoints

- `GET /api/list` — ranked pool. Params: kind (movie|series), q, page (0-based), pageSize (10|20|50|100).
- `GET /api/search?q=` — accent- and typo-tolerant title + people search. 30 queries/IP/minute.
- `POST /api/movies/batch` — body `{"ids":["tt…"]}` up to 100 ids. Pure read.
- Unknown `/api/*` paths → JSON 404 `{"error":{"code":"not_found","message":"…"}}`.

## Contract

- OpenAPI 3.1: https://goodrecmovies.com/openapi.json
- Versioning: current paths are `/api/*`; breaking changes move to `/api/v2/*`.
  Deprecated versions emit `Deprecation` + `Sunset` headers for ≥90 days (none today).
- Rate limits: per IP via `RateLimit-Policy` / `RateLimit-Limit`; 429 carries `Retry-After`.
- Errors: JSON `{"error":{"code","message"}}` on every failure.

## Related

- Docs portal: https://goodrecmovies.com/docs · section guide: https://goodrecmovies.com/docs/llms.txt
- NLWeb ask: `POST /ask` (not under /api, same auth: none)
- Full site guide: https://goodrecmovies.com/llms.txt