{"openapi":"3.0.3","info":{"title":"SteamGPT API","version":"1.3.0","description":"Structured Steam identity and gaming context API, designed for AI agents and search assistants that need factual public Steam player information. No auth, no cookies, no tracking. Append .md (markdown), .json (JSON) or .ai (deterministic plain text) to any data endpoint; default depends on Accept header. Errors carry a machine-readable `error` slug and follow the same format selection."},"servers":[{"url":"https://steamgpt.net"},{"url":"https://steamgpt.net/v1"}],"security":[{},{"boostToken":["rate-boost"]}],"components":{"securitySchemes":{"boostToken":{"type":"oauth2","description":"OPTIONAL. Every endpoint works without any credential. A self-service token (no registration, no client_id) raises the per-IP rate limit from 120 to 600 requests/min. Send it as: Authorization: Bearer <access_token>. Details: https://steamgpt.net/auth.md","flows":{"clientCredentials":{"tokenUrl":"https://steamgpt.net/oauth/token","scopes":{"rate-boost":"Higher per-IP rate limit (600/min instead of 120/min)"}}}}},"schemas":{"Error":{"type":"object","properties":{"result":{"type":"string","enum":["error"]},"code":{"type":"integer"},"error":{"type":"string","enum":["player_not_found","no_faceit_data","no_bans_data","batch_too_large","batch_no_valid_ids","bad_request","invalid_token","unknown_endpoint","rate_limited","internal"]},"message":{"type":"string"}},"required":["result","code","error"]},"Ids":{"type":"object","description":"All SteamID representations of the player","properties":{"steamid64":{"type":"string","example":"76561197960287930"},"steamid":{"type":"string","nullable":true,"example":"STEAM_1:0:11101"},"steamid3":{"type":"string","nullable":true,"example":"[U:1:22202]"}}},"SteamPlayer":{"type":"object","nullable":true,"description":"Raw Steam GetPlayerSummaries player object, unmodified field names","properties":{"steamid":{"type":"string"},"personaname":{"type":"string"},"profileurl":{"type":"string"},"avatar":{"type":"string"},"avatarmedium":{"type":"string"},"avatarfull":{"type":"string"},"personastate":{"type":"integer","description":"0 offline, 1 online, 2 busy, 3 away, 4 snooze, 5 looking to trade, 6 looking to play"},"communityvisibilitystate":{"type":"integer","description":"3 = public"},"timecreated":{"type":"integer","description":"unixtime"},"lastlogoff":{"type":"integer","description":"unixtime"},"gameextrainfo":{"type":"string"},"loccountrycode":{"type":"string"}},"additionalProperties":true},"Canonical":{"type":"object","description":"Stable resource identity: vanity and steamid64 URLs are the same resource","properties":{"steamid64":{"type":"string"},"url":{"type":"string"}}},"SourceProvenance":{"type":"object","properties":{"source":{"type":"string","example":"Steam Web API"},"retrieved_at":{"type":"integer","nullable":true,"description":"unixtime of the cached snapshot"},"age_seconds":{"type":"integer","nullable":true,"description":"snapshot age at response time"},"fresh":{"type":"boolean","description":"age within cache_ttl; false when unknown"},"cache_ttl":{"type":"integer","nullable":true,"description":"refresh policy in seconds"},"refreshed_with":{"type":"string","description":"steam_bans only: bans refresh together with this source snapshot"}}},"ProfileData":{"type":"object","properties":{"steamid64":{"type":"string"},"ids":{"$ref":"#/components/schemas/Ids"},"steam":{"$ref":"#/components/schemas/SteamPlayer"},"canonical":{"$ref":"#/components/schemas/Canonical"},"provenance":{"type":"object","properties":{"steam":{"$ref":"#/components/schemas/SourceProvenance"}}}}},"Profile":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"$ref":"#/components/schemas/ProfileData"}}},"FriendsData":{"type":"object","properties":{"count":{"type":"integer","description":"total known friends (may exceed shown list)"},"friends":{"type":"array","items":{"oneOf":[{"type":"string","description":"detail=short: plain steamid64"},{"type":"object","description":"detail=medium","properties":{"steamid64":{"type":"string"},"personaname":{"type":"string","nullable":true}}},{"type":"object","description":"detail=full (default)","properties":{"steamid64":{"type":"string"},"steam":{"$ref":"#/components/schemas/SteamPlayer"}}}]}}}},"Friends":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"$ref":"#/components/schemas/FriendsData"}}},"FaceitData":{"type":"object","properties":{"steamid64":{"type":"string"},"faceit":{"type":"object","nullable":true,"description":"FACEIT API player object (nickname, country, games.{cs2|csgo}.skill_level / faceit_elo, ...)","additionalProperties":true},"bans":{"type":"array","items":{"type":"object","additionalProperties":true}},"provenance":{"type":"object","properties":{"faceit":{"$ref":"#/components/schemas/SourceProvenance"}}}}},"Faceit":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"$ref":"#/components/schemas/FaceitData"}}},"Summary":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"type":"object","properties":{"steamid64":{"type":"string"},"ids":{"$ref":"#/components/schemas/Ids"},"steam":{"$ref":"#/components/schemas/SteamPlayer"},"faceit":{"type":"object","nullable":true,"additionalProperties":true},"faceit_bans":{"type":"array","items":{"type":"object","additionalProperties":true}},"steam_bans":{"type":"object","nullable":true,"description":"GetPlayerBans object; absent when include excludes bans","additionalProperties":true},"friends":{"$ref":"#/components/schemas/FriendsData"},"canonical":{"$ref":"#/components/schemas/Canonical"},"provenance":{"type":"object","description":"keys follow include: faceit / steam_bans absent when their blocks are excluded","properties":{"steam":{"$ref":"#/components/schemas/SourceProvenance"},"faceit":{"$ref":"#/components/schemas/SourceProvenance"},"steam_bans":{"$ref":"#/components/schemas/SourceProvenance"}}},"sources":{"type":"object","description":"per-source status: ok (data present), empty (no such data), unavailable (source did not answer - absence is NOT a fact), excluded (not requested)","properties":{"steam":{"type":"string","enum":["ok","empty","unavailable","excluded"]},"faceit":{"type":"string","enum":["ok","empty","unavailable","excluded"]},"friends":{"type":"string","enum":["ok","empty","unavailable","excluded"]},"bans":{"type":"string","enum":["ok","empty","unavailable","excluded"]}}},"partial":{"type":"boolean","description":"true when at least one source is unavailable"}}}}},"Compare":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"type":"object","properties":{"a":{"type":"object","description":"full summary data of the first player"},"b":{"type":"object","description":"full summary data of the second player"},"shared_friends":{"type":"object","properties":{"count":{"type":"integer"},"friends":{"type":"array","items":{"type":"object","properties":{"steamid64":{"type":"string"},"personaname":{"type":"string","nullable":true}}}}}}}}}},"Batch":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"type":"object","properties":{"count":{"type":"integer"},"players":{"type":"array","items":{"type":"object","description":"batch entry: no canonical/provenance; faceit and steam_bans appear only with include","properties":{"steamid64":{"type":"string"},"ids":{"$ref":"#/components/schemas/Ids"},"steam":{"$ref":"#/components/schemas/SteamPlayer"},"faceit":{"type":"object","nullable":true,"additionalProperties":true},"faceit_bans":{"type":"array","items":{"type":"object","additionalProperties":true}},"steam_bans":{"type":"object","nullable":true,"additionalProperties":true}}}},"not_found":{"type":"array","items":{"type":"string"},"description":"valid steamid64 not found in cache"},"invalid":{"type":"array","items":{"type":"string"},"description":"inputs that are not steamid64 (sanitized echo)"}}}}},"Bans":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"type":"object","properties":{"steamid64":{"type":"string"},"bans":{"type":"object","description":"Raw Steam GetPlayerBans object","properties":{"SteamId":{"type":"string"},"CommunityBanned":{"type":"boolean"},"VACBanned":{"type":"boolean"},"NumberOfVACBans":{"type":"integer"},"DaysSinceLastBan":{"type":"integer"},"NumberOfGameBans":{"type":"integer"},"EconomyBan":{"type":"string"}}},"provenance":{"type":"object","properties":{"steam_bans":{"$ref":"#/components/schemas/SourceProvenance"}}}}}}},"Converter":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"type":"object","description":"every representation of one account","properties":{"steamid64":{"type":"string","example":"76561198038416053"},"steamid64_hex":{"type":"string","example":"110000104a87ab5"},"steamid":{"type":"string","example":"STEAM_1:1:39075162"},"steamid_legacy":{"type":"string","example":"STEAM_0:1:39075162","description":"same account - STEAM_0 is the legacy universe digit"},"steamid3":{"type":"string","example":"[U:1:78150325]"},"accountid":{"type":"integer","example":78150325,"description":"32-bit account id"},"steam_hex":{"type":"string","example":"steam:110000104a87ab5","description":"hex form used by FiveM"},"profile_url":{"type":"string"},"input_format":{"type":"string","enum":["steamid64","steamid64_hex","steamid","steamid3","steam_hex","accountid","profile_url"],"description":"which format was detected on input"},"converted":{"type":"boolean","enum":[true]}}}}},"Identity":{"type":"object","properties":{"result":{"type":"string","enum":["success"]},"data":{"type":"object","properties":{"steamid64":{"type":"string","example":"76561197960287930"},"steamid":{"type":"string","nullable":true,"example":"STEAM_1:0:11101"},"steamid3":{"type":"string","nullable":true,"example":"[U:1:22202]"},"steam_hex":{"type":"string","nullable":true,"example":"steam:1100001000056ba","description":"hex form used by FiveM"},"vanity":{"type":"string","nullable":true,"description":"custom URL name when known, null otherwise"},"profile_url":{"type":"string"},"resolved":{"type":"boolean","enum":[true]}}}}}}},"paths":{"/summary/{id}":{"get":{"summary":"Use when a complete overview of a Steam player is needed. Steam summary + FACEIT + friends (size controlled by include / friends_limit)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"restricts the response to the listed blocks: steam, faceit, friends, bans. Omit for all of them; unknown values give 400"},{"name":"preset","in":"query","required":false,"schema":{"type":"string","enum":["identity","competitive","full"]},"description":"agent shorthand: identity = steam block only, competitive = faceit + bans, full = everything. Explicit include wins"},{"name":"friends_limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":100},"description":"cap the friend list"},{"name":"friends_detail","in":"query","required":false,"schema":{"type":"string","enum":["short","medium","full"]},"description":"friend entry shape"}],"responses":{"200":{"description":"Full aggregate: Steam + FACEIT + friends","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Summary"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"},"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Unknown include value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/{id}":{"get":{"summary":"Use when only the raw Steam profile is needed. Steam summary only (cheapest, fewest tokens)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name"}],"responses":{"200":{"description":"Steam summary only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"},"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/friends/{id}":{"get":{"summary":"Use when asked who a player plays or is friends with. Public Steam friend graph of a player (platform snapshot, can be partial)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name"},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["short","medium","full"],"default":"full"},"description":"short - plain steamid64 array (cheapest), medium - steamid64 + personaname, full - raw Steam summary objects"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":100},"description":"max friends to return"}],"responses":{"200":{"description":"Friend list (shape depends on ?detail)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Friends"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/faceit/{id}":{"get":{"summary":"Use when asked about FACEIT level, ELO or FACEIT bans. FACEIT player object and bans","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name"}],"responses":{"200":{"description":"FACEIT player object + bans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Faceit"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batch/{ids}":{"get":{"summary":"Use when checking several players at once. Up to 100 Steam profiles in one request (comma-separated ids in any SteamID format except vanity names). When checking many players, prefer one batch call over per-player requests","parameters":[{"name":"ids","in":"path","required":true,"schema":{"type":"string"},"description":"comma-separated ids, max 100, any SteamID format except vanity names, e.g. 76561197960287930,STEAM_1:1:39075162,[U:1:22202]"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"comma list: faceit, bans - one query / one upstream call for the whole batch"}],"responses":{"200":{"description":"players + not_found + invalid lists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"400":{"description":"More than 100 ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/converter/{id}":{"get":{"summary":"Use when you only need to convert an id between formats. Instant and free. Accepts steamid64, STEAM_1:0:x, STEAM_0:0:x, [U:1:x], hex, steam:hex, a 32-bit account id or a /profiles/ link (NOT a vanity name - use /identity for those)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64, STEAM_1:0:x, STEAM_0:0:x, [U:1:x], hex (110000...), steam:hex, a 32-bit account id or a steamcommunity.com/profiles/ link"}],"responses":{"200":{"description":"Every representation of the same account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Converter"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"},"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Not convertible by math (e.g. a vanity name - use /identity)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/identity/{id}":{"get":{"summary":"Use when converting or resolving Steam identifiers. Pure identifier resolver: all SteamID forms + vanity + profile URL, no profile data","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name"}],"responses":{"200":{"description":"All identifier representations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Identity"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bans/{id}":{"get":{"summary":"Use when asked whether an account has VAC, game, community or economy bans. Steam ban status exactly as Steam returns it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"steamid64 (17 digits), STEAM_1:0:x, [U:1:x], steamcommunity.com profile URL or vanity name"}],"responses":{"200":{"description":"GetPlayerBans object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bans"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compare/{id1}/{id2}":{"get":{"summary":"Use when comparing two players. Two players side by side: identity, account, bans, FACEIT and shared entries of the public friend graph","parameters":[{"name":"id1","in":"path","required":true,"schema":{"type":"string"},"description":"any SteamID form, steamcommunity link or vanity name"},{"name":"id2","in":"path","required":true,"schema":{"type":"string"},"description":"any SteamID form, steamcommunity link or vanity name"}],"responses":{"200":{"description":"Both summaries + shared friends","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Compare"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batch":{"post":{"summary":"Batch profiles via JSON body (same limits as GET /batch)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"ids as STRINGS in any SteamID format except vanity names - never JSON numbers, a 17-digit number loses precision and points at another account"},"include":{"type":"array","items":{"type":"string","enum":["faceit","bans"]}}},"required":["ids"]}}}},"responses":{"200":{"description":"players + not_found + invalid lists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}},"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"},"description":".ai deterministic text"}}},"400":{"description":"More than 100 ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 16kb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ready":{"get":{"summary":"Dependency readiness (database + cache)","responses":{"200":{"description":"All dependencies ok"},"503":{"description":"Degraded"}}}}}}