{"openapi":"3.0.3","info":{"title":"RetroBase Collection Public API","version":"1.0.0","description":"Read-only, hash-first retro game database API. Anonymous access allowed (60 req\/min per IP); pass an `X-Api-Key` header for 300 req\/min. Only redistributable data (open catalogs + community contributions) is served. Rate limit state is exposed via standard `X-RateLimit-*` headers.","contact":{"email":"contact@ixelia.fr","url":"https:\/\/retrobase-collection.com\/developers"},"license":{"name":"Open data \u2014 final license (ODbL expected) pending legal review","url":"https:\/\/retrobase-collection.com\/legal"}},"servers":[{"url":"https:\/\/retrobase-collection.com\/api\/public\/v1"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Optional. Raises the rate limit from 60 to 300 req\/min (1000 req\/min for supporter-tier keys). Create keys from your account settings."}},"schemas":{"Platform":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Sega Mega Drive"},"category":{"type":"string","enum":["CONSOLE","MAGAZINE"]}}},"Dump":{"type":"object","description":"A known dump fingerprint (no-intro \/ redump naming conventions).","properties":{"crc":{"type":"string","example":"50ABC90A"},"md5":{"type":"string","nullable":true},"sha1":{"type":"string","nullable":true},"size":{"type":"integer","nullable":true},"region":{"type":"string","nullable":true,"example":"eu"},"revision":{"type":"string","nullable":true},"dump_source":{"type":"string","nullable":true,"example":"no-intro"}}},"Media":{"type":"object","properties":{"type":{"type":"string","example":"box-2D"},"region":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"hash":{"type":"string","nullable":true,"description":"sha1 of the file content when hosted by RetroBase"}}},"Game":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Sonic The Hedgehog 2"},"names":{"type":"object","nullable":true,"description":"Regional names keyed by region code"},"platform":{"$ref":"#\/components\/schemas\/Platform"},"region":{"type":"string","nullable":true},"year":{"type":"string","nullable":true,"example":"1992"},"publisher":{"type":"string","nullable":true},"developer":{"type":"string","nullable":true},"genre":{"type":"string","nullable":true},"franchise":{"type":"string","nullable":true},"synopsis":{"type":"string","nullable":true},"media":{"type":"array","items":{"$ref":"#\/components\/schemas\/Media"}},"dumps":{"type":"array","items":{"$ref":"#\/components\/schemas\/Dump"}}}},"Meta":{"type":"object","properties":{"license":{"type":"string"},"attribution":{"type":"string"},"docs":{"type":"string","format":"uri"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}},"security":[[],{"ApiKey":[]}],"paths":{"\/lookup":{"get":{"summary":"Identify a ROM\/disc by fingerprint (the scraper workflow)","description":"Provide at least one of `crc`, `md5`, `sha1`. Add `size` and\/or `platform` to disambiguate. Responses are cacheable for 1 hour.","parameters":[{"name":"crc","in":"query","schema":{"type":"string","minLength":8,"maxLength":8},"example":"50ABC90A"},{"name":"md5","in":"query","schema":{"type":"string","minLength":32,"maxLength":32}},{"name":"sha1","in":"query","schema":{"type":"string","minLength":40,"maxLength":40}},{"name":"size","in":"query","schema":{"type":"integer"},"description":"File size in bytes"},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Platform id or name"}],"responses":{"200":{"description":"Matched game and dump entry","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"game":{"$ref":"#\/components\/schemas\/Game"},"dump":{"$ref":"#\/components\/schemas\/Dump"}}},"meta":{"$ref":"#\/components\/schemas\/Meta"}}}}}},"400":{"description":"Missing or malformed fingerprint","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"No redistributable match","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limited \u2014 check Retry-After"}}}},"\/games":{"get":{"summary":"Search games by name","description":"Typo-tolerant name search (trigram) within the redistributable subset.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"example":"sonic"},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Matching games (without dump lists \u2014 fetch \/games\/{id} for those)","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Game"}},"meta":{"allOf":[{"$ref":"#\/components\/schemas\/Meta"},{"type":"object","properties":{"total":{"type":"integer"}}}]}}}}}}}}},"\/games\/{id}":{"get":{"summary":"Full game record (dumps + free media)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Game","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Game"},"meta":{"$ref":"#\/components\/schemas\/Meta"}}}}}},"404":{"description":"Unknown or non-redistributable id","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/platforms":{"get":{"summary":"Reference list of platforms","responses":{"200":{"description":"Platforms","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Platform"}},"meta":{"$ref":"#\/components\/schemas\/Meta"}}}}}}}}},"\/status":{"get":{"summary":"Service status, public counters and rate limits","responses":{"200":{"description":"Status"}}}},"\/openapi.json":{"get":{"summary":"This specification","responses":{"200":{"description":"OpenAPI 3 document"}}}},"\/media-types":{"get":{"summary":"Media type taxonomy (ScreenScraper\/EmulationStation naming conventions)","responses":{"200":{"description":"List of {type, label, kind} \u2014 kind is image, video or pdf"}}}},"\/lookup\/batch":{"post":{"summary":"Identify up to 100 ROMs\/discs in one request (one rate-limit hit)","description":"Built for library scanners (RomM, Gaseous, Playmatch-style match cycles). Results are aligned with the input order; entries with no redistributable match (or no fingerprint) come back as null.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["lookups"],"properties":{"lookups":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","properties":{"crc":{"type":"string","minLength":8,"maxLength":8},"md5":{"type":"string","minLength":32,"maxLength":32},"sha1":{"type":"string","minLength":40,"maxLength":40},"size":{"type":"integer"},"platform":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Array of {game, dump} or null, same order as the input","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true,"type":"object","properties":{"game":{"$ref":"#\/components\/schemas\/Game"},"dump":{"$ref":"#\/components\/schemas\/Dump"}}}},"meta":{"$ref":"#\/components\/schemas\/Meta"}}}}}},"400":{"description":"Malformed batch (more than 100 entries, bad fingerprint format)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limited \u2014 check Retry-After"}}}}}}