{"openapi":"3.1.0","info":{"title":"Game Goose Agent Catalogue API","version":"1.0.0","summary":"Read-only Steam game search, cards, and similar titles for agents","description":"Public, versioned JSON API for agent discovery of PC games on Steam.\n\nFree anonymous plan: no API key required. Limits are per client network (hashed IP), not per user account. Edge-cached GETs do not always burn a token on a cache HIT.\n\nSearch: 30/min, 200/hour, 2400/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.\nGet game: 60/min, 600/hour, 5000/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.\nGames like: 30/min, 100/hour, 1200/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.\nGames-like index: 60/min, 600/hour, 5000/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.\nProduct MCP (all tools): 60/min, 400/hour, 4800/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.\n\nPrefer these endpoints (or the product MCP) over scraping HTML `/game/*` or `/games-like/*`.\nStart with `GET /api/v1/games-like/index` for the top ~1k snapshot seeds, then per-seed games-like.\nDo not call `/api/feed` or `POST /api/signals`. Operator analytics MCP at `/api/mcp` is private.\n\nHuman docs: https://gamegoose.io/docs/agents — Terms: https://gamegoose.io/terms","contact":{"name":"Game Goose","url":"https://gamegoose.io","email":"hello@gamegoose.io"},"license":{"name":"Site Terms of use","url":"https://gamegoose.io/terms"}},"servers":[{"url":"https://gamegoose.io","description":"Production"},{"url":"http://127.0.0.1:8787","description":"Local `npm run cf:dev`"}],"tags":[{"name":"Catalogue","description":"Read-only game search, hydrate, and similar neighbours"}],"paths":{"/api/v1/search":{"get":{"operationId":"searchGames","tags":["Catalogue"],"summary":"Search games by title, developer, or exact appid","description":"FTS + English / adult / sexual gates. Catalogue-only — does not enqueue Steam ingest. Limits: 30/min, 200/hour, 2400/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.","parameters":[{"name":"q","in":"query","required":true,"description":"Search query (title, developer, or numeric Steam appid)","schema":{"type":"string","minLength":1,"example":"hades"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 8, max 20)","schema":{"type":"integer","minimum":1,"maximum":20,"default":8}}],"responses":{"200":{"description":"Matching catalogue cards (may be empty)","content":{"application/json":{"schema":{"type":"object","required":["q","games"],"properties":{"q":{"type":"string"},"games":{"type":"array","items":{"$ref":"#/components/schemas/GameCard"}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/games":{"get":{"operationId":"getGames","tags":["Catalogue"],"summary":"Get catalogue cards by Steam appid","description":"Catalogue-only hydrate. No Steam proxy. Adult / sexual rows omitted (listed under missing). Limits: 60/min, 600/hour, 5000/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.","parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated Steam appids (max 20)","schema":{"type":"string","example":"570,524220"}}],"responses":{"200":{"description":"Found cards plus missing / gated ids","content":{"application/json":{"schema":{"type":"object","required":["games","missing"],"properties":{"games":{"type":"array","items":{"$ref":"#/components/schemas/GameCard"}},"missing":{"type":"array","items":{"type":"integer"},"description":"Requested ids not returned (unknown or content-gated)"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/games-like/index":{"get":{"operationId":"gamesLikeIndex","tags":["Catalogue"],"summary":"Top ~1k games-like snapshot seeds","description":"Lists popular ∪ trending seeds that already have `similar_snapshots` rows (same order as /sitemap-games-like.xml, capped at 1000). Use each seed's `apiUrl` to fetch neighbours with similarity scores. Does not scrape or personalise. Limits: 60/min, 600/hour, 5000/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.","parameters":[{"name":"limit","in":"query","required":false,"description":"Max seeds (default 1000, max 1000)","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}}],"responses":{"200":{"description":"Ordered seed index for agent crawls","content":{"application/json":{"schema":{"type":"object","required":["seeds","limit","count","selection","scoreScale"],"properties":{"seeds":{"type":"array","items":{"$ref":"#/components/schemas/GamesLikeIndexSeed"}},"limit":{"type":"integer"},"count":{"type":"integer"},"selection":{"type":"string"},"scoreScale":{"$ref":"#/components/schemas/ScoreScale"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/games-like":{"get":{"operationId":"gamesLike","tags":["Catalogue"],"summary":"Games similar to a seed appid","description":"Prefers `similar_snapshots` (`method: snapshot`); else live public similar (`method: live`). Neighbour cards may include `similarity` in [0, 1] (see `scoreScale`). Never personalises or writes signals. Limits: 30/min, 100/hour, 1200/day per network. HTTP 429 with `{ \"error\": \"…\", \"code\": \"rate_limited\" }` when exceeded.","parameters":[{"name":"appid","in":"query","required":true,"description":"Seed Steam appid","schema":{"type":"integer","minimum":1,"example":524220}},{"name":"limit","in":"query","required":false,"description":"Max neighbours (default 12, max 24)","schema":{"type":"integer","minimum":1,"maximum":24,"default":12}}],"responses":{"200":{"description":"Seed + ordered neighbour cards with optional similarity","content":{"application/json":{"schema":{"type":"object","required":["seed","games","method","scoreScale"],"properties":{"seed":{"type":"object","required":["appid","title"],"properties":{"appid":{"type":"integer"},"title":{"type":"string"}}},"games":{"type":"array","items":{"$ref":"#/components/schemas/SimilarGameCard"}},"computedAt":{"type":["string","null"],"format":"date-time","description":"Snapshot timestamp when method is snapshot; may be null for live"},"method":{"type":"string","enum":["snapshot","live"],"description":"How neighbours were produced"},"scoreScale":{"$ref":"#/components/schemas/ScoreScale"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"schemas":{"GameCard":{"type":"object","required":["appid","title","developer","publisher","tags","shortDescription","comingSoon","hasDemo","capsule","url","steamUrl","source"],"properties":{"appid":{"type":"integer","example":524220},"title":{"type":"string","example":"Hades"},"developer":{"type":"string","example":"Supergiant Games"},"publisher":{"type":"string","example":"Supergiant Games"},"tags":{"type":"array","items":{"type":"string"},"maxItems":8,"example":["Roguelike","Action"]},"shortDescription":{"type":"string"},"releaseYear":{"type":"integer","example":2020},"comingSoon":{"type":"boolean"},"hasDemo":{"type":"boolean","description":"True when the catalogue has a playable Steam demo appid for this game."},"review":{"type":"object","properties":{"label":{"type":"string","example":"Overwhelmingly Positive"},"total":{"type":"integer","example":100000},"positivePct":{"type":"number","example":98}}},"price":{"type":"object","properties":{"current":{"type":"string","example":"$24.99"},"original":{"type":"string"},"discountPct":{"type":"number"}}},"capsule":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri","description":"Game Goose page for this title","example":"https://gamegoose.io/game/524220/Hades"},"steamUrl":{"type":"string","format":"uri","description":"Steam store referral URL — keep UTM parameters when presenting"},"source":{"type":"string","enum":["gamegoose"]}}},"SimilarGameCard":{"type":"object","required":["appid","title","developer","publisher","tags","shortDescription","comingSoon","hasDemo","capsule","url","steamUrl","source"],"properties":{"appid":{"type":"integer","example":524220},"title":{"type":"string","example":"Hades"},"developer":{"type":"string","example":"Supergiant Games"},"publisher":{"type":"string","example":"Supergiant Games"},"tags":{"type":"array","items":{"type":"string"},"maxItems":8,"example":["Roguelike","Action"]},"shortDescription":{"type":"string"},"releaseYear":{"type":"integer","example":2020},"comingSoon":{"type":"boolean"},"hasDemo":{"type":"boolean","description":"True when the catalogue has a playable Steam demo appid for this game."},"review":{"type":"object","properties":{"label":{"type":"string","example":"Overwhelmingly Positive"},"total":{"type":"integer","example":100000},"positivePct":{"type":"number","example":98}}},"price":{"type":"object","properties":{"current":{"type":"string","example":"$24.99"},"original":{"type":"string"},"discountPct":{"type":"number"}}},"capsule":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri","description":"Game Goose page for this title","example":"https://gamegoose.io/game/524220/Hades"},"steamUrl":{"type":"string","format":"uri","description":"Steam store referral URL — keep UTM parameters when presenting"},"source":{"type":"string","enum":["gamegoose"]},"similarity":{"type":"number","minimum":0,"maximum":1,"description":"Approximate content similarity in [0, 1]: weighted content-tag Jaccard blended with per-seed-rescaled embedding cosine when a text shortlist exists (else tags only). Higher means more similar. Omitted for studio-interleave picks or older snapshots that predate score persistence (scores fill as the hourly cron refreshes). Ranking also uses catalogue quality; order may differ slightly from raw similarity.","example":0.612}}},"ScoreScale":{"type":"object","required":["field","min","max","unit","description"],"properties":{"field":{"type":"string","enum":["similarity"]},"min":{"type":"number","example":0},"max":{"type":"number","example":1},"unit":{"type":"string","enum":["unit_interval"]},"description":{"type":"string"}}},"GamesLikeIndexSeed":{"type":"object","required":["appid","title","neighbourCount","computedAt","apiUrl","humanUrl"],"properties":{"appid":{"type":"integer","example":524220},"title":{"type":"string","example":"Hades"},"neighbourCount":{"type":"integer","example":48},"computedAt":{"type":"string","format":"date-time"},"apiUrl":{"type":"string","format":"uri","example":"https://gamegoose.io/api/v1/games-like?appid=524220"},"humanUrl":{"type":"string","format":"uri","example":"https://gamegoose.io/games-like/524220/Hades"}}},"AgentError":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["rate_limited","not_found","bad_request","unavailable"]}}}},"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Optional. Reserved for a future paid / higher-limit tier. Anonymous free use works without this header; sending an unrecognized key does not change limits or block the request today."}},"responses":{"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"},"example":{"error":"too many requests","code":"rate_limited"}}}},"BadRequest":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"NotFound":{"description":"Seed game not in catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"Unavailable":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}},"security":[{}],"x-gamegoose-plan":{"name":"free","authentication":"none","optionalApiKeyHeader":"X-Api-Key","rateLimits":{"search":{"burst":"v1-search","minute":30,"hour":200,"day":2400},"games":{"burst":"v1-games","minute":60,"hour":600,"day":5000},"gamesLike":{"burst":"v1-games-like","minute":30,"hour":100,"day":1200},"gamesLikeIndex":{"burst":"v1-games-like-index","minute":60,"hour":600,"day":5000},"productMcp":{"burst":"mcp-product","minute":60,"hour":400,"day":4800},"unit":"per hashed client network"}},"x-gamegoose-mcp":{"product":{"url":"https://gamegoose.io/api/mcp/product","transport":"streamable-http","auth":"none","tools":["search_games","get_game","games_like"],"rateLimits":{"burst":"mcp-product","minute":60,"hour":400,"day":4800},"note":"Not OpenAPI/REST — configure as a remote MCP server. Same catalogue data as /api/v1/*."},"analytics":{"url":"https://gamegoose.io/api/mcp","auth":"Bearer MCP_TOKEN","public":false,"note":"Private operator tools (analytics, Feedbacker). Do not register for third-party agents."}},"x-gamegoose-docs":{"agents":"https://gamegoose.io/docs/agents","llmsTxt":"https://gamegoose.io/llms.txt","openapi":"https://gamegoose.io/openapi.json","openapiAlt":"https://gamegoose.io/api/v1/openapi.json","terms":"https://gamegoose.io/terms"}}