{ "openapi": "3.1.0", "info": { "title": "CSGOPremier Public API", "version": "1.0.0", "summary": "Read-only player, season and match data from csgopremier.com.", "description": "Read-only access to CSGOPremier's own data: seasons, leaderboards, player profiles, per-season records and finished matches.\n\n**Authentication.** Every data endpoint needs an API key, sent as `Authorization: Bearer ` (or `X-API-Key: `). Never put the key in a URL. Request access at https://csgopremier.com/developers.\n\n**Rate limits.** Each app has a per-minute budget with a burst allowance and a daily quota. Every response carries `RateLimit-*` and `X-Quota-*` headers; a 429 carries `Retry-After`. Requests without a valid key are limited per IP.\n\n**Caching.** Responses carry an `ETag`; send it back in `If-None-Match` to get a cheap `304 Not Modified`. `Cache-Control: max-age` says how long a response stays fresh.\n\n**Paging.** Lists return `meta.nextCursor`; pass it as `cursor` for the next page. It is `null` on the last page.\n\n**Errors.** Errors are `{\"error\": {\"code\", \"message\", \"requestId\"}}`; switch on `code`.\n\n**Units.** Win and headshot rates are fractions from 0 to 1. Times are UTC, RFC 3339.", "contact": { "name": "CSGOPremier developers", "url": "https://csgopremier.com/developers" }, "termsOfService": "https://csgopremier.com/developers/docs#terms" }, "servers": [ { "url": "https://public-api.csgopremier.com", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Meta", "description": "Health and this specification." }, { "name": "Seasons", "description": "Seasons, leaderboards and skill groups." }, { "name": "Players", "description": "Player profiles, season records and match history." }, { "name": "Matches", "description": "Finished match scoreboards." }, { "name": "Maps", "description": "The map catalogue." } ], "paths": { "/v1/status": { "get": { "operationId": "getStatus", "summary": "Service status", "description": "Health check. Needs no key, never touches the database, and is not rate limited per app.", "tags": [ "Meta" ], "parameters": [], "responses": { "200": { "description": "The service is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Status" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "status": "ok", "version": "3f2a9c1", "time": "2026-11-05T12:00:00Z" } } } } } }, "security": [] } }, "/v1/openapi.json": { "get": { "operationId": "getOpenAPI", "summary": "This specification", "description": "The OpenAPI 3.1 document for this API. Needs no key.", "tags": [ "Meta" ], "parameters": [], "responses": { "200": { "description": "OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "$ref": "#/components/responses/NotModified" } }, "security": [] } }, "/v1/seasons": { "get": { "operationId": "listSeasons", "summary": "List seasons", "description": "The active season and every ended season, newest first. Draft seasons are never listed.", "tags": [ "Seasons" ], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Season" } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [ { "id": 9, "number": 5, "name": "Season 5", "status": "active", "startedAt": "2026-10-01T00:00:00Z", "endedAt": null, "endsAt": "2027-01-01T00:00:00Z", "ratingCap": 74999, "trophyImageUrl": "https://csgopremier.com/static/seasons/9/1f0c.png" } ] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/seasons/{season}": { "get": { "operationId": "getSeason", "summary": "Get a season", "description": "One season by number, or `current`.", "tags": [ "Seasons" ], "parameters": [ { "$ref": "#/components/parameters/season" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Season" } }, "required": [ "data" ], "additionalProperties": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/seasons/{season}/leaderboard": { "get": { "operationId": "getLeaderboard", "summary": "Season leaderboard", "description": "Ranked players of one season and title. Mirrors the site's boards: players currently banned, unplaced players and deleted accounts are left out. Equal ratings share a rank (1, 2, 2, 4). The board is a snapshot rebuilt about every minute for the current season (`meta.generatedAt`).", "tags": [ "Seasons" ], "parameters": [ { "$ref": "#/components/parameters/season" }, { "$ref": "#/components/parameters/game" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardEntry" } }, "meta": { "$ref": "#/components/schemas/LeaderboardMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/ranks": { "get": { "operationId": "listRanks", "summary": "Skill groups", "description": "The 18 skill groups (Silver I to Global Elite) with their rating ranges and medal images. Both titles share one rating scale; the CS2 site shows the number with colour tiers instead of medals.", "tags": [ "Seasons" ], "parameters": [ { "$ref": "#/components/parameters/game" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SkillGroup" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/maps": { "get": { "operationId": "listMaps", "summary": "List maps", "description": "Every map that can be queued in at least one mode, with its image and modes.", "tags": [ "Maps" ], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Map" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/players": { "get": { "operationId": "lookupPlayers", "summary": "Look up players", "description": "Batch lookup. Pass exactly one of `ids` (up to 50), `steamIds` (up to 50, any supported format) or `username` (current username, case-insensitive). Results keep the request order; inputs with no public player are listed in `meta.notFound`.", "tags": [ "Players" ], "parameters": [ { "$ref": "#/components/parameters/ids" }, { "$ref": "#/components/parameters/steamIds" }, { "$ref": "#/components/parameters/username" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Player" } }, "meta": { "$ref": "#/components/schemas/BatchMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/players/steam/{steamId}": { "get": { "operationId": "getPlayerBySteamId", "summary": "Get a player by Steam ID", "description": "Accepts SteamID64 (`76561198…`), `STEAM_0:1:23`, `[U:1:47]` or a bare account id. Vanity names are not resolved.", "tags": [ "Players" ], "parameters": [ { "$ref": "#/components/parameters/steamIdPath" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Player" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": 4211, "username": "s1mpleFan", "steamId": "76561198000000001", "avatarUrl": "https://csgopremier.com/static/avatars/4211/2b1c.jpg", "countryCode": "NL", "profileUrl": "https://csgopremier.com/s1mpleFan", "premiumTier": "premium", "banned": false, "currentSeason": 5, "ratings": { "csgo": { "rating": 18250, "placed": true, "placementWinsRemaining": 0, "skillGroup": { "id": 13, "key": "mge", "name": "Master Guardian Elite", "minRating": 17500, "maxRating": 19999, "imageUrl": "https://csgopremier.com/static/classic_ranks/mge.svg" }, "rank": 412, "wins": 61, "matches": 109, "winRate": 0.5596 }, "cs2": { "rating": null, "placed": false, "placementWinsRemaining": 4, "skillGroup": null, "rank": null, "wins": 2, "matches": 3, "winRate": 0.6667 } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/players/{id}": { "get": { "operationId": "getPlayer", "summary": "Get a player", "description": "A player's public profile. Ids are stable; usernames can change.", "tags": [ "Players" ], "parameters": [ { "$ref": "#/components/parameters/playerId" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Player" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": 4211, "username": "s1mpleFan", "steamId": "76561198000000001", "avatarUrl": "https://csgopremier.com/static/avatars/4211/2b1c.jpg", "countryCode": "NL", "profileUrl": "https://csgopremier.com/s1mpleFan", "premiumTier": "premium", "banned": false, "currentSeason": 5, "ratings": { "csgo": { "rating": 18250, "placed": true, "placementWinsRemaining": 0, "skillGroup": { "id": 13, "key": "mge", "name": "Master Guardian Elite", "minRating": 17500, "maxRating": 19999, "imageUrl": "https://csgopremier.com/static/classic_ranks/mge.svg" }, "rank": 412, "wins": 61, "matches": 109, "winRate": 0.5596 }, "cs2": { "rating": null, "placed": false, "placementWinsRemaining": 4, "skillGroup": null, "rank": null, "wins": 2, "matches": 3, "winRate": 0.6667 } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/players/{id}/seasons": { "get": { "operationId": "listPlayerSeasons", "summary": "A player's seasons", "description": "The current season plus every ended season the player has a record in, newest first. K/D statistics exist for CS:GO only.", "tags": [ "Players" ], "parameters": [ { "$ref": "#/components/parameters/playerId" }, { "$ref": "#/components/parameters/game" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerSeason" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/players/{id}/seasons/{season}": { "get": { "operationId": "getPlayerSeason", "summary": "A player's season", "description": "One season record with the per-map win/loss record.", "tags": [ "Players" ], "parameters": [ { "$ref": "#/components/parameters/playerId" }, { "$ref": "#/components/parameters/season" }, { "$ref": "#/components/parameters/game" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlayerSeasonDetail" } }, "required": [ "data" ], "additionalProperties": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/players/{id}/matches": { "get": { "operationId": "listPlayerMatches", "summary": "A player's matches", "description": "Finished matches of one title, newest first. `ratingChange` is the published change the site shows, or null (placement, unrated mode, reverted or invalidated).", "tags": [ "Players" ], "parameters": [ { "$ref": "#/components/parameters/playerId" }, { "$ref": "#/components/parameters/game" }, { "$ref": "#/components/parameters/seasonQuery" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerMatch" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } }, "/v1/matches/{id}": { "get": { "operationId": "getMatch", "summary": "Get a match", "description": "Scoreboard of a finished match. Live and unfinished matches return 404. Deleted accounts appear with `player: null`.", "tags": [ "Matches" ], "parameters": [ { "$ref": "#/components/parameters/matchId" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Match" } }, "required": [ "data" ], "additionalProperties": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Overloaded" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cpk_…", "description": "Authorization: Bearer cpk_…" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative to the Authorization header." } }, "parameters": { "season": { "name": "season", "in": "path", "required": true, "description": "Season number (e.g. `5`) or `current`.", "schema": { "type": "string", "pattern": "^([1-9][0-9]*|current)$" }, "example": "current" }, "seasonQuery": { "name": "season", "in": "query", "required": false, "description": "Only matches of this season (number or `current`).", "schema": { "type": "string", "pattern": "^([1-9][0-9]*|current)$" } }, "game": { "name": "game", "in": "query", "required": false, "description": "Game title. Defaults to `csgo`.", "schema": { "type": "string", "enum": [ "csgo", "cs2" ], "default": "csgo" } }, "limit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from `meta.nextCursor`.", "schema": { "type": "string" } }, "playerId": { "name": "id", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "matchId": { "name": "id", "in": "path", "required": true, "description": "Match id.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "steamIdPath": { "name": "steamId", "in": "path", "required": true, "description": "SteamID64, STEAM_X:Y:Z, [U:1:N] or account id.", "schema": { "type": "string" }, "example": "76561198000000001" }, "ids": { "name": "ids", "in": "query", "required": false, "description": "Comma-separated player ids (max 50).", "schema": { "type": "string" }, "example": "4211,90,1337" }, "steamIds": { "name": "steamIds", "in": "query", "required": false, "description": "Comma-separated Steam IDs in any supported format (max 50).", "schema": { "type": "string" } }, "username": { "name": "username", "in": "query", "required": false, "description": "Current username, case-insensitive.", "schema": { "type": "string", "maxLength": 32 } } }, "headers": { "RateLimit-Limit": { "description": "Burst size: requests you may send at once.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests you may send right now.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the burst budget is full again.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "`;w=60;burst=`.", "schema": { "type": "string" } }, "X-Quota-Limit": { "description": "Daily request quota (resets 00:00 UTC).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requests left today.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "ETag": { "description": "Entity tag; send it in If-None-Match.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Quote this when reporting a problem.", "schema": { "type": "string" } } }, "responses": { "NotModified": { "description": "Not modified: your cached copy (If-None-Match) is current." }, "BadRequest": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "limit must be between 1 and 100", "requestId": "9f1c2a7d3b4e5f60" } } } } }, "Unauthorized": { "description": "Missing, invalid, revoked or suspended key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "A valid API key is required. Send it as Authorization: Bearer .", "requestId": "9f1c2a7d3b4e5f60" } } } } }, "Forbidden": { "description": "The request's Origin or IP address is not allowed for this app (`origin_not_allowed`, `ip_not_allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such public resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit (`rate_limited`) or daily quota (`quota_exceeded`) reached.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Limit": { "$ref": "#/components/headers/X-Quota-Limit" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Wait for Retry-After seconds.", "requestId": "9f1c2a7d3b4e5f60" } } } } }, "Overloaded": { "description": "The API is busy; retry after `Retry-After` seconds with backoff.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "origin_not_allowed", "ip_not_allowed", "not_found", "bad_request", "rate_limited", "quota_exceeded", "overloaded", "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Status": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" }, "time": { "type": "string", "format": "date-time" } }, "required": [ "status", "version", "time" ], "additionalProperties": false }, "Season": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "number": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "ended" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "oneOf": [ { "type": "string", "format": "date-time", "description": "Planned end of the active season." }, { "type": "null" } ] }, "ratingCap": { "type": "integer", "description": "Highest rating reachable this season." }, "trophyImageUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "number", "name", "status", "startedAt", "endedAt", "endsAt", "ratingCap", "trophyImageUrl" ], "additionalProperties": false }, "SeasonRef": { "type": "object", "properties": { "number": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "ended" ] } }, "required": [ "number", "name", "status" ], "additionalProperties": false }, "SkillGroup": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 18 }, "key": { "type": "string" }, "name": { "type": "string" }, "minRating": { "type": "integer" }, "maxRating": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "imageUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "key", "name", "minRating", "maxRating", "imageUrl" ], "additionalProperties": false }, "PlayerRef": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "username": { "type": "string" }, "steamId": { "oneOf": [ { "type": "string", "description": "SteamID64" }, { "type": "null" } ] }, "avatarUrl": { "type": "string", "format": "uri" }, "countryCode": { "oneOf": [ { "type": "string", "description": "ISO 3166-1 alpha-2" }, { "type": "null" } ] } }, "required": [ "id", "username", "steamId", "avatarUrl", "countryCode" ], "additionalProperties": false }, "GameRating": { "type": "object", "properties": { "rating": { "oneOf": [ { "type": "integer", "description": "Null until placed (six wins)." }, { "type": "null" } ] }, "placed": { "type": "boolean" }, "placementWinsRemaining": { "type": "integer" }, "skillGroup": { "oneOf": [ { "$ref": "#/components/schemas/SkillGroup" }, { "type": "null" } ] }, "rank": { "oneOf": [ { "type": "integer", "description": "Current-season leaderboard rank." }, { "type": "null" } ] }, "wins": { "type": "integer" }, "matches": { "type": "integer" }, "winRate": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "rating", "placed", "placementWinsRemaining", "skillGroup", "rank", "wins", "matches", "winRate" ], "additionalProperties": false }, "Player": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "username": { "type": "string" }, "steamId": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "avatarUrl": { "type": "string", "format": "uri" }, "countryCode": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "profileUrl": { "type": "string", "format": "uri" }, "premiumTier": { "type": "string", "enum": [ "none", "basic", "premium", "max" ] }, "banned": { "type": "boolean", "description": "An active matchmaking ban. Cooldowns and chat restrictions are not included." }, "currentSeason": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "ratings": { "type": "object", "properties": { "csgo": { "$ref": "#/components/schemas/GameRating" }, "cs2": { "$ref": "#/components/schemas/GameRating" } }, "required": [ "csgo", "cs2" ], "additionalProperties": false } }, "required": [ "id", "username", "steamId", "avatarUrl", "countryCode", "profileUrl", "premiumTier", "banned", "currentSeason", "ratings" ], "additionalProperties": false }, "LeaderboardEntry": { "type": "object", "properties": { "rank": { "type": "integer" }, "player": { "$ref": "#/components/schemas/PlayerRef" }, "rating": { "type": "integer" }, "skillGroup": { "oneOf": [ { "$ref": "#/components/schemas/SkillGroup" }, { "type": "null" } ] }, "wins": { "type": "integer" }, "matches": { "type": "integer" }, "winRate": { "type": "number" } }, "required": [ "rank", "player", "rating", "skillGroup", "wins", "matches", "winRate" ], "additionalProperties": false }, "LeaderboardMeta": { "type": "object", "properties": { "season": { "type": "integer" }, "game": { "type": "string", "enum": [ "csgo", "cs2" ] }, "total": { "type": "integer" }, "generatedAt": { "type": "string", "format": "date-time" }, "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "limit": { "type": "integer" } }, "required": [ "season", "game", "total", "generatedAt", "nextCursor", "limit" ], "additionalProperties": false }, "SeasonStats": { "type": "object", "properties": { "gamesTracked": { "type": "integer" }, "kills": { "type": "integer" }, "deaths": { "type": "integer" }, "assists": { "type": "integer" }, "headshots": { "type": "integer" }, "kdRatio": { "type": "number" }, "avgKills": { "type": "number" }, "adr": { "oneOf": [ { "type": "number", "description": "Average damage per round; only counts games with round tracking (from 19 June 2026)." }, { "type": "null" } ] }, "headshotRate": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "gamesTracked", "kills", "deaths", "assists", "headshots", "kdRatio", "avgKills", "adr", "headshotRate" ], "additionalProperties": false }, "PlayerSeason": { "type": "object", "properties": { "season": { "$ref": "#/components/schemas/SeasonRef" }, "game": { "type": "string", "enum": [ "csgo", "cs2" ] }, "rating": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "placed": { "type": "boolean" }, "skillGroup": { "oneOf": [ { "$ref": "#/components/schemas/SkillGroup" }, { "type": "null" } ] }, "rank": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "wins": { "type": "integer" }, "matches": { "type": "integer" }, "winRate": { "type": "number" }, "stats": { "oneOf": [ { "$ref": "#/components/schemas/SeasonStats" }, { "type": "null" } ] } }, "required": [ "season", "game", "rating", "placed", "skillGroup", "rank", "wins", "matches", "winRate", "stats" ], "additionalProperties": false }, "PlayerSeasonDetail": { "type": "object", "properties": { "season": { "$ref": "#/components/schemas/SeasonRef" }, "game": { "type": "string", "enum": [ "csgo", "cs2" ] }, "rating": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "placed": { "type": "boolean" }, "skillGroup": { "oneOf": [ { "$ref": "#/components/schemas/SkillGroup" }, { "type": "null" } ] }, "rank": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "wins": { "type": "integer" }, "matches": { "type": "integer" }, "winRate": { "type": "number" }, "stats": { "oneOf": [ { "$ref": "#/components/schemas/SeasonStats" }, { "type": "null" } ] }, "maps": { "type": "array", "items": { "$ref": "#/components/schemas/MapRecord" } } }, "required": [ "season", "game", "rating", "placed", "skillGroup", "rank", "wins", "matches", "winRate", "stats", "maps" ], "additionalProperties": false }, "MapRef": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "imageUrl": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "slug", "name", "imageUrl" ], "additionalProperties": false }, "MapRecord": { "type": "object", "properties": { "map": { "$ref": "#/components/schemas/MapRef" }, "wins": { "type": "integer" }, "losses": { "type": "integer" }, "winRate": { "type": "number" } }, "required": [ "map", "wins", "losses", "winRate" ], "additionalProperties": false }, "Score": { "type": "object", "properties": { "team": { "type": "integer" }, "opponent": { "type": "integer" } }, "required": [ "team", "opponent" ], "additionalProperties": false }, "PlayerMatch": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "game": { "type": "string", "enum": [ "csgo", "cs2" ] }, "mode": { "type": "string", "description": "e.g. premier5v5, premier5v5_ladder, premier2v2, premier1v1, cs2_premier5v5" }, "map": { "$ref": "#/components/schemas/MapRef" }, "season": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "playedAt": { "type": "string", "format": "date-time" }, "team": { "type": "string", "enum": [ "A", "B" ] }, "score": { "$ref": "#/components/schemas/Score" }, "result": { "type": "string", "enum": [ "win", "loss", "unknown" ] }, "ratingChange": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "ratingInvalidated": { "type": "boolean" } }, "required": [ "id", "game", "mode", "map", "season", "playedAt", "team", "score", "result", "ratingChange", "ratingInvalidated" ], "additionalProperties": false }, "MatchStats": { "type": "object", "properties": { "kills": { "type": "integer" }, "deaths": { "type": "integer" }, "assists": { "type": "integer" }, "damage": { "type": "integer" }, "headshots": { "type": "integer" } }, "required": [ "kills", "deaths", "assists", "damage", "headshots" ], "additionalProperties": false }, "MatchPlayer": { "type": "object", "properties": { "player": { "oneOf": [ { "$ref": "#/components/schemas/PlayerRef" }, { "type": "null" } ] }, "team": { "type": "string", "enum": [ "A", "B" ] }, "stats": { "oneOf": [ { "$ref": "#/components/schemas/MatchStats" }, { "type": "null" } ] }, "ratingChange": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "player", "team", "stats", "ratingChange" ], "additionalProperties": false }, "Match": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "game": { "type": "string", "enum": [ "csgo", "cs2" ] }, "mode": { "type": "string" }, "map": { "$ref": "#/components/schemas/MapRef" }, "region": { "type": "string" }, "season": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "startedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedAt": { "type": "string", "format": "date-time" }, "score": { "type": "object", "properties": { "a": { "type": "integer" }, "b": { "type": "integer" } }, "required": [ "a", "b" ], "additionalProperties": false }, "winner": { "oneOf": [ { "type": "string", "enum": [ "A", "B" ] }, { "type": "null" } ] }, "ratingInvalidated": { "type": "boolean" }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/MatchPlayer" } } }, "required": [ "id", "game", "mode", "map", "region", "season", "startedAt", "endedAt", "score", "winner", "ratingInvalidated", "players" ], "additionalProperties": false }, "Map": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "game": { "type": "string", "enum": [ "csgo", "cs2" ] }, "category": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" }, "modes": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "game", "category", "imageUrl", "modes" ], "additionalProperties": false }, "ListMeta": { "type": "object", "properties": { "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "limit": { "type": "integer" } }, "required": [ "nextCursor", "limit" ], "additionalProperties": false }, "BatchMeta": { "type": "object", "properties": { "notFound": { "type": "array", "items": { "type": "string" } } }, "required": [ "notFound" ], "additionalProperties": false } } } }