# goodrecmovies for developers & agents

Free, unauthenticated, read-only API over the movie ranking. No keys, no OAuth.

## Endpoints

- GET /api/list — the list, best first. kind (movie|series), q, page (0-based), pageSize (10|20|50|100). Rows carry title facts and tier.
- GET /api/search?q=... — accent- and typo-tolerant title + people search. Rows carry title facts. 30 queries per IP per minute.
- POST /api/movies/batch — up to 100 IMDb ids, pure read. Rows carry title facts and tier.
- POST /ask — NLWeb natural-language answers; JSON, or SSE with prefer.streaming.

## Machine-readable

- OpenAPI 3.1: /openapi.json
- MCP: /.well-known/mcp/server-card.json (transport /mcp — movies_selection, search_titles, get_title, similar_titles)
- Errors: JSON {"error":{"code","message"}} everywhere, including unknown /api/* paths.
- Rate limits: per IP, RateLimit-Policy header; 429 carries Retry-After.

HTML version: /docs