goodrecmovies for developers & agents

A free, unauthenticated, read-only API over the movie ranking — every movie above 7.0, ranked by math, not vibes. No keys, no sign-up, no OAuth.

Quickstart

GET /api/list?kind=movie&pageSize=10 returns the top of the ranking, best first — each row carries rank, tier, and goodrecIndex (the raw value behind the GRM display score, GRM = value / 2 + 50). Try it: /api/list?kind=movie&pageSize=10

Endpoints

GET /api/list — ranked pool. Params: kind (movie|series), q (title filter), page (0-based), pageSize (10|20|50|100). Response: rows + total + poolN — walk pages until total.

GET /api/search?q=… — accent- and typo-tolerant title search plus cast/director hits. 30 queries per IP per minute.

POST /api/movies/batch — up to 100 IMDb ids, pure read, retries always safe.

POST /ask — natural language in, ranked answers out (NLWeb: JSON with _meta, or SSE with prefer.streaming).

Full request/response schemas: /openapi.json (OpenAPI 3.1 — import into any client generator or LLM function-calling setup).

Auth

None. Every operation is public and anonymous — no keys, no OAuth, no accounts. Details in /auth.md; RFC 9728 metadata at /.well-known/oauth-protected-resource.

Rate limits

Per IP, in real time: responses carry RateLimit-Policy (e.g. 30;w=60 on search); exceeding it returns 429 with Retry-After. Back off and retry — nothing idempotency-unsafe can happen, the API defines no write operations.

Errors

Machine-readable JSON on every failure: {"error": {"code": "bad_request", "message": "…"}} — agents should read code, humans the message.

Also available

llms.txt (machine guide) · MCP server card (transport /mcp: top_titles, search_titles, get_title) · agent skills · Markdown everywhere (.md twin per page) · agent docs repo · official MCP registry listing

Questions or data corrections: hello@goodrecmovies.com.