# goodrecmovies docs

> Developer & agent portal for the goodrecmovies public ranking API — read-only,
> unauthenticated, best-first movie and series lists.

## When to use this section

Use /docs when you need the API contract, rate limits, or error model — not the
human ranking UI.

## Endpoints

- `GET /api/list` — ranked titles, best first (`kind`, `q`, `page`, `pageSize`)
- `GET /api/search?q=` — fuzzy title + people search (30/IP/min)
- `POST /api/movies/batch` — up to 100 IMDb ids, pure read
- `POST /ask` — NLWeb natural-language answers (JSON or SSE)

## Machine surfaces

- OpenAPI 3.1: https://goodrecmovies.com/openapi.json
- Auth (none for reads): https://goodrecmovies.com/auth.md
- Pricing (free): https://goodrecmovies.com/pricing.md
- MCP product: https://goodrecmovies.com/.well-known/mcp/server-card.json → /mcp (origin)
- MCP docs twin: https://goodrecmovies.com/.well-known/mcp/docs-server-card.json → /mcp/docs
- Smithery install: https://smithery.ai/servers/trdrmorz/goodrecmovies — `npx -y smithery mcp add trdrmorz/goodrecmovies`
- Section guide (API): https://goodrecmovies.com/api/llms.txt
- Skills (skills.sh): https://www.skills.sh/0xm0w/goodrecmovies-agents — install: `npx skills add 0xm0w/goodrecmovies-agents`
- Full site guide: https://goodrecmovies.com/llms.txt

HTML portal: https://goodrecmovies.com/docs