{ "openapi": "3.1.0", "info": { "title": "Pillage Public API", "version": "1.0.0", "description": "Public read-only Minecraft server data. No API key required. GET/HEAD/OPTIONS with CORS *. Default quota: 120 requests/minute/IP. Poll no more often than every 30\u201360 seconds; use ETags and back off on 429/503. All text must be rendered as plain text. Counters and metric values are decimal strings. Dates are UTC. Sources remain authoritative; queried time is not a last-game-update time." }, "servers": [ { "url": ".", "description": "The directory containing this OpenAPI document; works behind a URL prefix." } ], "security": [], "paths": { "/v1/status": { "get": { "operationId": "Public online status", "summary": "Public online status", "description": "Only the configured Minecraft component. probeTimeExact=false identifies a separately queried recent-probe timestamp. Stale or unverifiable player counts are omitted.", "parameters": [], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnlineResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/overview": { "get": { "operationId": "Overview", "summary": "Overview", "description": "Sources have independent availability. HTTP 503 only when every source is unavailable. This aggregate is not CDN cached.", "parameters": [], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverviewResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/firsts": { "get": { "operationId": "Resolved Legacy entries", "summary": "Resolved Legacy entries", "description": "Includes effective owner corrections and adopted manual entries, never admin/audit fields. happened and holders are independent.", "parameters": [], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirstsResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/leaderboards": { "get": { "operationId": "Leaderboard", "summary": "Leaderboard", "description": "Positions follow Core top() ordering. Positive competitive values only; K/D honors the public policy thresholds. Playtime is persisted milliseconds, not unbanked session time.", "parameters": [ { "name": "metric", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "kills", "deaths", "kd", "unique_kills", "highest_kill_streak", "playtime" ] } }, { "name": "scope", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "all-time", "year" ] } }, { "name": "year", "in": "query", "required": false, "description": "Allowed only for scope=year; defaults to the current UTC year.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/champions": { "get": { "operationId": "Year champions", "summary": "Year champions", "description": "", "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Defaults to the current UTC year.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChampionsResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/history": { "get": { "operationId": "Public server history", "summary": "Public server history", "description": "PUBLIC + SERVER/BOTH + BIOGRAPHY only. Unknown metadata is not serialized. Order: occurred_at descending, then ID descending.", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "all", "firsts", "records", "years" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page, bound to kind.", "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nexus": { "get": { "operationId": "Public Nexus topology", "summary": "Public Nexus topology", "description": "Excludes BROKEN nodes and incident links. No coordinates, seeds, contributor names or contributor UUIDs. A missing network document is NOT_READY, not an invented empty network.", "parameters": [], "responses": { "200": { "description": "Successful read. A zero or empty list is not an error.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkResponse" } } } }, "304": { "description": "Unchanged ETag" }, "400": { "description": "Invalid or repeated query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or disabled category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; respect Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Source unavailable, not ready, unsupported schema or busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/healthz": { "get": { "operationId": "Liveness", "responses": { "200": { "description": "HTTP process is running." } } } }, "/readyz": { "get": { "operationId": "Readiness", "responses": { "200": { "description": "Core source can be read with supported schema." }, "503": { "description": "Core source unavailable or unsupported." } } } } }, "components": { "schemas": { "Player": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uuid", "name" ] }, "Meta": { "type": "object", "additionalProperties": false, "properties": { "source": { "type": "string", "enum": [ "core", "nexus", "status" ] }, "consistency": { "type": "string", "enum": [ "committed", "probe" ] }, "readAt": { "type": "string", "format": "date-time" } }, "required": [ "source", "consistency", "readAt" ] }, "CoreOverview": { "type": "object", "additionalProperties": false, "properties": { "uniquePlayers": { "type": "string", "pattern": "^[0-9]+$" }, "kills": { "type": "string", "pattern": "^[0-9]+$" }, "competitiveDeaths": { "type": "string", "pattern": "^[0-9]+$" }, "recordedPlaytimeMillis": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "uniquePlayers", "kills", "competitiveDeaths", "recordedPlaytimeMillis" ] }, "First": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "enum": [ "automatic", "manual" ] }, "happened": { "type": "boolean" }, "holders": { "type": "array", "items": { "$ref": "#/components/schemas/Player" } }, "achievedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "key", "title", "description", "source", "happened", "holders", "achievedAt" ] }, "Firsts": { "type": "object", "additionalProperties": false, "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/First" } }, "claimed": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "policyVersion": { "type": "string" } }, "required": [ "entries", "claimed", "total", "policyVersion" ] }, "Qualification": { "type": "object", "additionalProperties": false, "properties": { "minimumKills": { "type": "integer", "minimum": 0 }, "minimumDeaths": { "type": "integer", "minimum": 0 } }, "required": [ "minimumKills", "minimumDeaths" ] }, "Standing": { "type": "object", "additionalProperties": false, "properties": { "position": { "type": "integer", "minimum": 1 }, "player": { "$ref": "#/components/schemas/Player" }, "value": { "type": "string" } }, "required": [ "position", "player", "value" ] }, "Leaderboard": { "type": "object", "additionalProperties": false, "properties": { "metric": { "type": "string", "enum": [ "kills", "deaths", "kd", "unique_kills", "highest_kill_streak", "playtime" ] }, "scope": { "type": "string", "enum": [ "all-time", "year" ] }, "year": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "unit": { "type": "string", "enum": [ "count", "ratio", "milliseconds" ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/Standing" } }, "totalQualified": { "type": "string", "pattern": "^[0-9]+$" }, "limit": { "type": "integer", "minimum": 0 }, "qualification": { "oneOf": [ { "$ref": "#/components/schemas/Qualification" }, { "type": "null" } ] }, "policyVersion": { "type": "string" } }, "required": [ "metric", "scope", "year", "unit", "rows", "totalQualified", "limit", "qualification", "policyVersion" ] }, "Champion": { "type": "object", "additionalProperties": false, "properties": { "category": { "type": "string", "enum": [ "most-kills", "highest-kill-streak", "most-unique-players-killed", "most-playtime" ] }, "player": { "$ref": "#/components/schemas/Player" }, "value": { "type": "string" }, "unit": { "type": "string", "enum": [ "count", "milliseconds" ] } }, "required": [ "category", "player", "value", "unit" ] }, "Champions": { "type": "object", "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "yearState": { "type": "string", "enum": [ "open", "archived" ] }, "archivedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "champions": { "type": "array", "items": { "$ref": "#/components/schemas/Champion" } } }, "required": [ "year", "yearState", "archivedAt", "champions" ] }, "Event": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "type": { "type": "string", "enum": [ "SERVER_FIRST", "RECORD_BROKEN", "YEAR_STARTED", "YEAR_ARCHIVED" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "primary": { "oneOf": [ { "$ref": "#/components/schemas/Player" }, { "type": "null" } ] }, "secondary": { "oneOf": [ { "$ref": "#/components/schemas/Player" }, { "type": "null" } ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "firstKey": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "occurredAt", "primary", "secondary", "title", "detail", "firstKey" ] }, "History": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "server" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "scope", "items", "nextCursor" ] }, "Node": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "BUILDING", "ACTIVE", "SUSPENDED" ] }, "level": { "type": "integer", "minimum": 1, "maximum": 3 }, "foundedAt": { "type": "string", "format": "date-time" }, "contributorCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "name", "status", "level", "foundedAt", "contributorCount" ] }, "Link": { "type": "object", "additionalProperties": false, "properties": { "from": { "type": "string", "format": "uuid" }, "to": { "type": "string", "format": "uuid" }, "usable": { "type": "boolean" } }, "required": [ "from", "to", "usable" ] }, "NetworkCounts": { "type": "object", "additionalProperties": false, "properties": { "visibleNodes": { "type": "integer", "minimum": 0 }, "activeNodes": { "type": "integer", "minimum": 0 }, "visibleLinks": { "type": "integer", "minimum": 0 }, "usableLinks": { "type": "integer", "minimum": 0 }, "uniqueContributors": { "type": "integer", "minimum": 0 } }, "required": [ "visibleNodes", "activeNodes", "visibleLinks", "usableLinks", "uniqueContributors" ] }, "Network": { "type": "object", "additionalProperties": false, "properties": { "networkId": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[0-9]+$" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "counts": { "$ref": "#/components/schemas/NetworkCounts" }, "unsupportedMetrics": { "type": "array", "items": { "type": "string", "enum": [ "tripsToday", "travellersToday" ] } } }, "required": [ "networkId", "revision", "nodes", "links", "counts", "unsupportedMetrics" ] }, "Online": { "type": "object", "additionalProperties": false, "properties": { "componentId": { "type": "string" }, "state": { "type": "string", "enum": [ "operational", "degraded", "down", "unknown" ] }, "players": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "online": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 0 } }, "required": [ "online", "max" ] }, { "type": "null" } ] }, "probeObservedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "probeTimeExact": { "type": "boolean" }, "lastProbeOk": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "componentId", "state", "players", "probeObservedAt", "probeTimeExact", "lastProbeOk" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "CoreOverviewResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/CoreOverview" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "FirstsResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Firsts" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "LeaderboardResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Leaderboard" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "ChampionsResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Champions" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "HistoryResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/History" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "NetworkResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Network" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "OnlineResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Online" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "apiVersion", "realmId", "data", "meta" ] }, "OverviewResponse": { "type": "object", "additionalProperties": false, "properties": { "apiVersion": { "type": "string", "enum": [ "1" ] }, "realmId": { "type": "string" }, "data": { "type": "object", "additionalProperties": false, "properties": { "core": { "type": "object", "additionalProperties": false, "properties": { "availability": { "type": "string", "enum": [ "available", "unavailable" ] }, "data": { "oneOf": [ { "$ref": "#/components/schemas/CoreOverview" }, { "type": "null" } ] }, "readAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "availability", "data", "readAt" ] }, "nexus": { "type": "object", "additionalProperties": false, "properties": { "availability": { "type": "string", "enum": [ "available", "unavailable" ] }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Network" }, { "type": "null" } ] }, "readAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "availability", "data", "readAt" ] }, "online": { "type": "object", "additionalProperties": false, "properties": { "availability": { "type": "string", "enum": [ "available", "unavailable" ] }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Online" }, { "type": "null" } ] }, "readAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "availability", "data", "readAt" ] } }, "required": [ "core", "nexus", "online" ] } }, "required": [ "apiVersion", "realmId", "data" ] } } } }