{"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"]}}}}