goodrecmovies public API API

Read-only access to the goodrecmovies ranking (only the good stuff, zero filler). Versioning policy: the current version is served at /api/*; breaking changes move to /api/v2/* with this spec updated first — no breaking change ships in place. Deprecation policy: when an endpoint or version is schedu

GitHub OpenAPI

Operations 4

GET /api/list Ranked titles, best first #
GET /api/search Fuzzy title and people search #
POST /api/movies/batch Fetch up to 100 titles by IMDb id #
POST /ask Natural-language question over the ranking (NLWeb) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/goodrecmovies-com:goodrecmovies-public-api-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

goodrecmovies-com-api-openapi.json Raw ↑
{"openapi":"3.1.0","info":{"title":"goodrecmovies public API","version":"1.0.0","description":"Read-only access to the goodrecmovies ranking (only the good stuff, zero filler). Versioning policy: the current version is served at /api/*; breaking changes move to /api/v2/* with this spec updated first — no breaking change ships in place. Deprecation policy: when an endpoint or version is scheduled for removal, primary responses carry RFC 9745 Deprecation and RFC 8594 Sunset headers for at least 90 days notice before removal. Both headers are declared in components.headers. All operations are unauthenticated: there are no API keys and no OAuth; see /auth.md. Rate limits are per IP and surfaced in the RateLimit-Policy response header; 429 responses carry Retry-After.","contact":{"name":"goodrecmovies","email":"hello@goodrecmovies.com","url":"https://goodrecmovies.com/contact"},"license":{"name":"Data: IMDb public datasets + TMDB","url":"https://www.themoviedb.org"},"x-versioning-policy":{"current":"v1","pathPrefix":"/api/*","breakingChangePrefix":"/api/v2/*","transport":"path-prefix on breaking change only","deprecationWindowDays":90,"responseHeaders":{"Deprecation":{"spec":"RFC 9745","value":"true","description":"Present (and true) on every response from a deprecated API version."},"Sunset":{"spec":"RFC 8594","value":"HTTP-date","description":"Planned removal instant; always paired with Deprecation for ≥90 days before removal."}},"note":"No /api path is deprecated today. Breaking changes move to /api/v2/*; this OpenAPI is updated first."},"x-deprecation-policy":{"windowDays":90,"deprecationHeader":"Deprecation","sunsetHeader":"Sunset","noticeUrl":"https://goodrecmovies.com/docs#versioning","description":"No breaking change ships in place. Breaking changes move to /api/v2/* with this OpenAPI spec updated first. Deprecated endpoints return RFC 9745 Deprecation and RFC 8594 Sunset headers for at least 90 days before removal."}},"servers":[{"url":"https://goodrecmovies.com","description":"v1 — current stable. Versioning policy: paths are /api/*; breaking changes move to /api/v2/* with this spec updated first; a deprecated version returns Deprecation + Sunset headers for at least 90 days before removal."}],"security":[],"x-versioning-policy":{"current":"v1","pathPrefix":"/api/*","breakingChangePrefix":"/api/v2/*","transport":"path-prefix on breaking change only","deprecationWindowDays":90,"responseHeaders":{"Deprecation":{"spec":"RFC 9745","value":"true","description":"Present (and true) on every response from a deprecated API version."},"Sunset":{"spec":"RFC 8594","value":"HTTP-date","description":"Planned removal instant; always paired with Deprecation for ≥90 days before removal."}},"note":"No /api path is deprecated today. Breaking changes move to /api/v2/*; this OpenAPI is updated first."},"x-deprecation-policy":{"windowDays":90,"deprecationHeader":"Deprecation","sunsetHeader":"Sunset","noticeUrl":"https://goodrecmovies.com/docs#versioning","description":"No breaking change ships in place. Breaking changes move to /api/v2/* with this OpenAPI spec updated first. Deprecated endpoints return RFC 9745 Deprecation and RFC 8594 Sunset headers for at least 90 days before removal."},"tags":[{"name":"ranking","description":"The ranked pools"},{"name":"search","description":"Title and people search"},{"name":"ask","description":"Natural-language answers (NLWeb)"}],"paths":{"/api/list":{"get":{"tags":["ranking"],"operationId":"listTitles","summary":"Ranked titles, best first","deprecated":false,"description":"Paginated ranked pool. Pagination: `page` is 0-based, `pageSize` one of 10/20/50/100; the response carries total and page so clients can walk the set. Filters (q, kind) narrow the pool before ranking.","parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["movie","series"]},"description":"Pool to rank. Default movie."},{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"description":"Title substring filter."},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"pageSize","in":"query","schema":{"type":"integer","enum":[10,20,50,100],"default":100}}],"responses":{"200":{"description":"Ranked page","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"e.g. 60;w=60 — per-IP policy"},"RateLimit-Limit":{"schema":{"type":"string"},"description":"e.g. 60 — requests allowed per window"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"tconst":{"type":"string","description":"IMDb id, e.g. tt0111161"},"kind":{"type":"string","enum":["movie","series"]},"primaryTitle":{"type":"string"},"startYear":{"type":"integer","nullable":true},"runtimeMin":{"type":"integer","nullable":true},"genres":{"type":"array","items":{"type":"string"}},"votes":{"type":"integer","nullable":true},"tier":{"type":"string","enum":["solid","great","excellent","essential"]},"overview":{"type":"string","nullable":true}}}},"total":{"type":"integer","description":"Rows matching the filters"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/search":{"get":{"tags":["search"],"operationId":"searchTitles","summary":"Fuzzy title and people search","deprecated":false,"description":"Accent- and typo-tolerant search across both pools plus cast/director hits. Unauthenticated, rate limited to 30 queries per IP per minute (RateLimit-Policy).","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Matches (empty q returns trending)","headers":{"RateLimit-Policy":{"schema":{"type":"string"},"description":"e.g. 30;w=60 — per-IP policy"},"RateLimit-Limit":{"schema":{"type":"string"},"description":"e.g. 30 — requests allowed per window"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/movies/batch":{"post":{"tags":["ranking"],"operationId":"getTitlesBatch","summary":"Fetch up to 100 titles by IMDb id","deprecated":false,"description":"Batch lookup. Idempotency: this is a pure read (no side effects), so retries are safe without an Idempotency-Key — the API defines no write operations.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":128},"required":false,"description":"Accepted on every POST for client retry safety. The API defines no write operations — every operation is a pure read and already idempotent — so the key is honored, not recorded."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","pattern":"^tt\\d+$"},"maxItems":5000}},"required":["ids"]}}}},"responses":{"200":{"description":"Found titles","headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ask":{"post":{"tags":["ask"],"operationId":"ask","summary":"Natural-language question over the ranking (NLWeb)","deprecated":false,"description":"Accepts {\"query\": \"...\", \"prefer\": {\"streaming\": true}}. Returns NLWeb-shaped JSON (_meta.response_type + version) or text/event-stream with start/result/complete events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200},"prefer":{"type":"object","properties":{"streaming":{"type":"boolean"}}}},"required":["query"]}}}},"responses":{"200":{"description":"NLWeb answer (JSON) or SSE stream","headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"headers":{"Deprecation":{"description":"RFC 9745 — present only once an endpoint (or the API version) is deprecated: date or true. Absent on all endpoints today (no deprecated paths).","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594 — HTTP-date of planned removal. Always paired with Deprecation for ≥90 days before removal. Absent on all endpoints today.","schema":{"type":"string","format":"date-time"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["bad_request","rate_limited"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}