goodrecmovies Developer Portal & API Documentation

A free, unauthenticated, read-only API over the movie ranking — only the good stuff, zero filler. 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 the title, year, votes and its tier band. Try it: /api/list?kind=movie&pageSize=10

REST API Endpoints

GET /api/list — ranked pool. Params: kind (movie|series), q (title filter), page (0-based), pageSize (10|20|50|100). Response: rows + total — 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).

OpenAPI 3.1 Specification

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

Model Context Protocol (MCP Server)

goodrecmovies exposes a standard Model Context Protocol (MCP) server for Claude, ChatGPT, Cursor, and autonomous agents. Server card: /.well-known/mcp/server-card.json, streamable HTTP transport at /mcp (tools: movies_selection, search_titles, get_title, similar_titles). Dedicated docs MCP twin at /mcp/docs (tool: fetch_docs).

Official SDKs & CLI

npm install goodrecmovies — the official TypeScript/JavaScript client wraps every endpoint above: topTitles, searchTitles, getTitle, ask (typed, zero-config, no key). The same calls from the terminal via the bundled grm CLI: grm top series 10, grm search "godfather", grm title tt0111161, grm ask "best horror tonight?". Full README and examples on npm.

Python client: see the Python SDK in the goodrecmovies-agents repository.

Authentication & Security (auth.md)

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 & Quotas (pricing.md)

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. Details in /pricing.md.

Errors

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

REST Versioning & Deprecation Policy

Current paths are /api/*. Breaking changes move to /api/v2/* with openapi.json updated first. Deprecated versions emit Deprecation + Sunset response headers for at least 90 days (none today — see x-versioning-policy and x-deprecation-policy in the OpenAPI document).

Machine Guides (llms.txt) & Agent Discovery

llms.txt (machine guide) · docs/llms.txt · api/llms.txt · MCP server card (transport /mcp: movies_selection, search_titles, get_title, similar_titles) · A2A agent card (JSON-RPC /a2a) · Web Bot Auth key directory (outbound request signing) · agent skills · install via skills.sh: 0xm0w/goodrecmovies-agents (npx skills add 0xm0w/goodrecmovies-agents) · Markdown everywhere (.md twin per page) · agent docs repo · official MCP registry listing · Smithery: trdrmorz/goodrecmovies (npx -y smithery mcp add trdrmorz/goodrecmovies; origin transport stays /mcp)

Questions or data corrections: hello@goodrecmovies.com.