# GAMEMONITORING > The GAMEMONITORING REST API returns JSON data about servers, players, posts, online history and votes. This page covers integration basics and your first request. Endpoint pages provide parameters and request testing. - [GAMEMONITORING API](https://gamemonitoring.net/developers/docs/api.md) - [GAMEMONITORING MCP](https://gamemonitoring.net/developers/docs/mcp.md) - [Add server](https://gamemonitoring.net/developers/docs/api/servers/__post.md) - [Server](https://gamemonitoring.net/developers/docs/api/servers/:server_id/__get.md) - [Server players](https://gamemonitoring.net/developers/docs/api/servers/:server_id/players/__get.md) - [Posts mentioning the server](https://gamemonitoring.net/developers/docs/api/servers/:server_id/posts/__get.md) - [Server player count chart](https://gamemonitoring.net/developers/docs/api/servers/:server_id/stats/players_online/__get.md) - [Server votes](https://gamemonitoring.net/developers/docs/api/servers/:server_id/votes/__get.md) - [Server vote chart](https://gamemonitoring.net/developers/docs/api/servers/:server_id/votes/chart/__get.md) - [Server top voters](https://gamemonitoring.net/developers/docs/api/servers/:server_id/votes/top/__get.md) - [Project player count chart](https://gamemonitoring.net/developers/docs/api/projects/:project_id/stats/players_online/__get.md) - [Project votes](https://gamemonitoring.net/developers/docs/api/projects/:project_id/votes/__get.md) - [Project vote chart](https://gamemonitoring.net/developers/docs/api/projects/:project_id/votes/chart/__get.md) - [Project top voters](https://gamemonitoring.net/developers/docs/api/projects/:project_id/votes/top/__get.md) - [Vote](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/__get.md) - [Acknowledge vote processing](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/claim/__post.md) - [User profile](https://gamemonitoring.net/developers/docs/api/users/:id/__get.md) - [Verify account ownership](https://gamemonitoring.net/developers/docs/api/users/verify-code/__post.md) - [Webhook](https://gamemonitoring.net/developers/docs/webhook.md) - [Vote Rewards](https://gamemonitoring.net/developers/docs/webhook/vote.md) - [System IP addresses](https://gamemonitoring.net/developers/docs/ips.md) - [OpenAPI](https://gamemonitoring.net/developers/docs/openapi.json) - [Full documentation](https://gamemonitoring.net/developers/docs/llms-full.txt) - [GAMEMONITORING MCP](https://api.gamemonitoring.net/mcp) --- # GAMEMONITORING API The GAMEMONITORING REST API returns JSON data about servers, players, posts, online history and votes. This page covers integration basics and your first request. Endpoint pages provide parameters and request testing. ## Base URL https://api.gamemonitoring.net ## Your first request Start with public server data. Find the server ID at the end of its page URL on GAMEMONITORING. ```bash curl --header 'Accept: application/json' 'https://api.gamemonitoring.net/servers/1' ``` ## Choose an endpoint - [POST /servers — Add server](https://gamemonitoring.net/developers/docs/api/servers/__post.md) - [GET /servers/{server_id} — Server](https://gamemonitoring.net/developers/docs/api/servers/:server_id/__get.md) - [GET /servers/{server_id}/players — Server players](https://gamemonitoring.net/developers/docs/api/servers/:server_id/players/__get.md) - [GET /servers/{server_id}/posts — Posts mentioning the server](https://gamemonitoring.net/developers/docs/api/servers/:server_id/posts/__get.md) - [GET /servers/{server_id}/stats/players_online — Server player count chart](https://gamemonitoring.net/developers/docs/api/servers/:server_id/stats/players_online/__get.md) - [GET /servers/{server_id}/votes — Server votes](https://gamemonitoring.net/developers/docs/api/servers/:server_id/votes/__get.md) - [GET /servers/{server_id}/votes/chart — Server vote chart](https://gamemonitoring.net/developers/docs/api/servers/:server_id/votes/chart/__get.md) - [GET /servers/{server_id}/votes/top — Server top voters](https://gamemonitoring.net/developers/docs/api/servers/:server_id/votes/top/__get.md) - [GET /projects/{project_id}/stats/players_online — Project player count chart](https://gamemonitoring.net/developers/docs/api/projects/:project_id/stats/players_online/__get.md) - [GET /projects/{project_id}/votes — Project votes](https://gamemonitoring.net/developers/docs/api/projects/:project_id/votes/__get.md) - [GET /projects/{project_id}/votes/chart — Project vote chart](https://gamemonitoring.net/developers/docs/api/projects/:project_id/votes/chart/__get.md) - [GET /projects/{project_id}/votes/top — Project top voters](https://gamemonitoring.net/developers/docs/api/projects/:project_id/votes/top/__get.md) - [GET /votes/{vote_id} — Vote](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/__get.md) - [POST /votes/{vote_id}/claim — Acknowledge vote processing](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/claim/__post.md) - [GET /users/{id} — User profile](https://gamemonitoring.net/developers/docs/api/users/:id/__get.md) - [POST /users/verify-code — Verify account ownership](https://gamemonitoring.net/developers/docs/api/users/verify-code/__post.md) ## API versions Use the optional v query parameter to select an API version. The current version is 1.0.0. The version determines the available paths, request fields and response format. Without v, requests use the lowest supported version. When that version is retired, the next lowest supported version becomes the default. Specify v to keep a fixed contract. An invalid, repeated or unsupported version returns HTTP 400; unsupported versions include error.data.supported_versions. ## Passing parameters IDs go in the request path: server_id and project_id are numeric GAMEMONITORING IDs; vote_id identifies a vote. Replace each parameter in braces with its actual value. Pass filters, periods and pagination after ? in the URL. Encode values with URLSearchParams or your library’s equivalent, especially nicknames and search text. To add a server, send JSON with Content-Type: application/json. connect is a public host:port; steam_app_id is the game’s Steam App ID. Use query when the query and connection ports differ. ## Data format HTTP 200 wraps the result in response. Depending on the endpoint, it is an object, an array or an object with items. Follow the endpoint schema; an empty list is not an error by itself. Some fields may be null or omitted. These differ from 0, false and an empty string; handle missing data separately. created_at, expires_at and last_update use Unix timestamps in seconds. Multiply by 1000 for a JavaScript Date; divide Date.now() by 1000 and round down when building a filter. Keep 64-bit Steam identifiers as strings. Converting them to a JavaScript Number can lose precision. A GAMEMONITORING server ID and a game’s Steam App ID are different identifiers. ## Errors and retries Check the HTTP status and the error object: code contains the status, message explains it, and data provides additional details when available. Message text depends on the region and may change; do not use it as a condition in your code. Fix parameter or access errors before retrying. Also handle network errors and proxy responses that may not contain JSON. Data reflects the last server query and may be cached. Check last_update, use a reasonable refresh interval and cache results in your integration. Polling the API frequently does not make the game server update faster. ## Voting and Webhooks To react to a new vote, configure a project Webhook. Verify signature, skip test events with is_test=true and use event_id as vote_id to fetch the vote from the API. Check entity_type and entity_id, then process the event once using event_type + event_id. Acknowledge test events with a 2xx response without granting a reward. ## Integration support When reporting an error, include the HTTP method, path, parameters, request time, HTTP status and returned error. These details help reproduce the issue. ## OpenAPI ```json { "openapi": "3.1.1", "info": { "title": "GAMEMONITORING", "version": "1.0.0" }, "paths": { "/servers": { "post": { "operationId": "createServer", "summary": "Add server", "description": "Adds a server by connection address or returns the existing server.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connect": { "type": "string", "minLength": 1, "example": "198.51.100.24:27015" }, "steam_app_id": { "type": "integer", "minimum": 0, "example": 730 }, "query": { "type": "integer", "minimum": 10, "maximum": 65535, "example": 27016 } }, "required": [ "connect", "steam_app_id" ] }, "example": { "connect": "198.51.100.24:27015", "steam_app_id": 730 } } } }, "responses": { "200": { "description": "Created or existing server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCreateResult" }, "example": { "response": { "connect": "198.51.100.24:27015", "game": 730, "id": 100001, "name": "Example Arena", "request": "198.51.100.24:27016", "status": true } } } } }, "400": { "description": "Missing game or address, invalid address or offline server" }, "403": { "description": "Blocked address" }, "409": { "description": "Query address is already in use" }, "503": { "description": "Server creation service is unavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}": { "get": { "operationId": "getServer", "summary": "Server", "description": "Returns public server data.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Server details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerEnvelope" }, "example": { "response": { "steam_id": "90123456789012345", "domain": null, "id": 1, "ip": "198.51.100.24", "port": 27015, "query": 27015, "project_id": 42, "color": 0, "city": "Prague", "description": "[]", "game": 730, "boosts": 3, "last_offline": 1782751200, "last_online": 1783201200, "icon": null, "name": "Example CS2 Server", "connect": "198.51.100.24:27015", "request": "198.51.100.24:27015", "map": "de_mirage", "gamemode": "Counter-Strike 2", "version": "1.41.6.5", "numplayers": 12, "maxplayers": 64, "bots": 0, "secured": true, "private": false, "country": "CZ", "status": true, "votes": 128, "points": 2450, "add_date": 1701541119, "last_update": 1783201200, "ban_reason": null, "banned": false, "wipe": null, "official": null, "wipe_period": null, "next_wipe": null, "pve": null, "pvp": null, "list_hidden": false, "hide_address": false, "hide_query": false, "position_game": 12, "language": "en", "parked": false, "app": { "id": 2, "steam_id": 730, "name": "Counter-Strike 2", "url": "counter-strike-2" }, "mods": [ { "id": 5, "name": "Admin System" }, { "id": 14, "name": "Advertisement" }, { "id": 9, "name": "Admins" }, { "id": 3, "name": "Admin Commands" } ], "disabled_modules": [] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/players": { "get": { "operationId": "getServerPlayers", "summary": "Server players", "description": "Returns the server's player list.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "limit", "in": "query", "description": "Number of items from 1 to 100, default 50", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 5 } }, { "$ref": "#/components/parameters/offset" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Server players", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPlayersResult" }, "example": { "response": { "items": [ { "avatar": "no.jpg", "created": 1783200000, "last_online": 1783203600, "last_session_time": 0, "name": "NovaPlayer", "user": null, "username": null } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/servers/{server_id}/posts": { "get": { "operationId": "getServerPosts", "summary": "Posts mentioning the server", "description": "Returns public posts with a visible mention of the specified server.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "before_created_at", "in": "query", "description": "For the next page, send the last post’s `created_at` in Unix seconds as `before_created_at` and its `id` as `before_id`. Keep the same filters. The cursor works when `sort` and `period` are omitted. Use `offset` if either is set.", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "before_id", "in": "query", "description": "Cursor post ID", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "conversation_post_id", "in": "query", "description": "Conversation post ID", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "period", "in": "query", "description": "Use top to select the top-post period.", "schema": { "type": "string", "const": "top" } }, { "name": "reply_to_post_id", "in": "query", "description": "Parent post ID", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "root_only", "in": "query", "description": "Use 1 to return root posts only", "schema": { "type": "number", "const": 1 } }, { "name": "sort", "in": "query", "description": "Ordering of posts. For top posts, use helpful-desc.", "schema": { "type": "string" } }, { "name": "visibility", "in": "query", "description": "Only public posts are returned by this operation.", "schema": { "type": "string", "const": "public" } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "limit", "in": "query", "description": "Number of items from 1 to 100, default 20", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 5 } }, { "$ref": "#/components/parameters/offset" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 120, "example": "admin" } } ], "responses": { "200": { "description": "Public posts mentioning the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPostsResult" }, "example": { "response": [ { "id": 1001, "comment": "Great server! Thanks to the admin team.", "conversation_post_id": null, "language": "en", "moderation_needed": false, "replays": 0, "reply_to_post_id": null, "views": 25, "updated_at": null, "created_at": 1783200000, "translated_content": null, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user" }, "images": [], "mentions": [ { "type": "server", "meta": { "game": { "id": 2, "name": "Counter-Strike 2", "steam_id": 730, "url": "counter-strike-2" }, "icon": null, "id": 1, "name": "Example CS2 Server" } } ], "reactions": [], "replays_items": [], "replays_items_count": 0 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Server not found" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/stats/players_online": { "get": { "operationId": "getServerPlayerStats", "summary": "Server player count chart", "description": "Returns a player count chart with the minimum, average and maximum for each interval.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "type", "in": "query", "description": "Statistics period: day, week or month; default month", "schema": { "type": "string", "default": "month", "example": "week", "enum": [ "day", "week", "month" ] } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Player statistics grouped by time interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPlayerStatsResult" }, "example": { "response": { "items": [ { "avg_players": 12, "date": 1783200000, "maps": [ "de_mirage" ], "max_players": 16, "min_players": 8, "x": 1783200000, "y": 16 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/votes": { "get": { "operationId": "getServerVotes", "summary": "Server votes", "description": "Returns votes for the specified server.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "user_id", "in": "query", "description": "User identifier", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/claimed" }, { "$ref": "#/components/parameters/nickname" }, { "$ref": "#/components/parameters/created" }, { "$ref": "#/components/parameters/created__gt" }, { "$ref": "#/components/parameters/created__gte" }, { "$ref": "#/components/parameters/created__lt" }, { "$ref": "#/components/parameters/created__lte" }, { "$ref": "#/components/parameters/expire" }, { "$ref": "#/components/parameters/expire__gt" }, { "$ref": "#/components/parameters/expire__gte" }, { "$ref": "#/components/parameters/expire__lt" }, { "$ref": "#/components/parameters/expire__lte" } ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/VoteDetails" } } }, "required": [ "response" ] }, "example": { "response": [ { "claimed_at": null, "created_at": 1783200000, "entity_id": 42, "entity_type": "server", "expires_at": 1783243200, "id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "nickname": "NovaPlayer", "server": { "app": { "id": 2, "name": "Counter-Strike 2", "steam_id": 730, "url": "counter-strike-2" }, "game": 730, "icon": null, "id": 42, "name": "Example CS2 Server" }, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [] } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/votes/chart": { "get": { "operationId": "getServerVoteChart", "summary": "Server vote chart", "description": "Returns the number of votes per day.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "integer", "string" ] }, "y": { "type": [ "integer", "string" ] } } } } }, "required": [ "response" ] }, "example": { "response": [ { "x": 1800000000, "y": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/servers/{server_id}/votes/top": { "get": { "operationId": "getServerTopVoters", "summary": "Server top voters", "description": "Returns users with the most votes.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "active": { "type": [ "integer", "string" ] }, "total": { "type": [ "integer", "string" ] } } }, "last": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "nickname": { "type": "string" } } }, "user": { "type": "object", "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": "string" } } } } } } }, "required": [ "response" ] }, "example": { "response": [ { "counts": { "active": 2, "total": 10 }, "last": { "created_at": 1783200000, "expire_at": 1783243200, "nickname": "NovaPlayer" }, "user": { "avatar": "no.jpg", "username": "demo_user" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/projects/{project_id}/stats/players_online": { "get": { "operationId": "getProjectPlayerStats", "summary": "Project player count chart", "description": "Returns the minimum, average and maximum combined player count across project servers for each interval.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "type", "in": "query", "description": "Statistics period: day, week or month; default month", "schema": { "type": "string", "default": "month", "example": "week", "enum": [ "day", "week", "month" ] } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Combined project player statistics grouped by time interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPlayerStatsResult" }, "example": { "response": { "items": [ { "avg_players": 12, "date": 1783200000, "max_players": 16, "min_players": 8, "x": 1783200000 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/projects/{project_id}/votes": { "get": { "operationId": "getProjectVotes", "summary": "Project votes", "description": "Returns votes for the project. Only public projects are accessible without authentication.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "user_id", "in": "query", "description": "User identifier", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/claimed" }, { "$ref": "#/components/parameters/nickname" }, { "$ref": "#/components/parameters/created" }, { "$ref": "#/components/parameters/created__gt" }, { "$ref": "#/components/parameters/created__gte" }, { "$ref": "#/components/parameters/created__lt" }, { "$ref": "#/components/parameters/created__lte" }, { "$ref": "#/components/parameters/expire" }, { "$ref": "#/components/parameters/expire__gt" }, { "$ref": "#/components/parameters/expire__gte" }, { "$ref": "#/components/parameters/expire__lt" }, { "$ref": "#/components/parameters/expire__lte" } ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/VoteDetails" } } }, "required": [ "response" ] }, "example": { "response": [ { "claimed_at": null, "created_at": 1783200000, "entity_id": 42, "entity_type": "project", "expires_at": 1785792000, "id": "7206f073-2f18-4660-91b8-bd947fbc4be2", "nickname": "NovaPlayer", "project": { "id": 42 }, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [] } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/projects/{project_id}/votes/chart": { "get": { "operationId": "getProjectVoteChart", "summary": "Project vote chart", "description": "Returns daily vote counts for the project. Only public projects are accessible without authentication.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "integer", "string" ] }, "y": { "type": [ "integer", "string" ] } } } } }, "required": [ "response" ] }, "example": { "response": [ { "x": 1800000000, "y": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/projects/{project_id}/votes/top": { "get": { "operationId": "getProjectTopVoters", "summary": "Project top voters", "description": "Returns users with the most votes for the project. Only public projects are accessible without authentication.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "active": { "type": [ "integer", "string" ] }, "total": { "type": [ "integer", "string" ] } } }, "last": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "nickname": { "type": "string" } } }, "user": { "type": "object", "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": "string" } } } } } } }, "required": [ "response" ] }, "example": { "response": [ { "counts": { "active": 2, "total": 10 }, "last": { "created_at": 1783200000, "expire_at": 1785792000, "nickname": "NovaPlayer" }, "user": { "avatar": "no.jpg", "username": "demo_user" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/votes/{vote_id}": { "get": { "operationId": "getVote", "summary": "Vote", "description": "Returns vote details by ID.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "vote_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" } } ], "responses": { "200": { "description": "Vote details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteDetailsEnvelope" }, "example": { "response": { "created_at": 1783200000, "expires_at": 1783243200, "id": "6f59a4a8-2f0f-4d96-a50a-9d7a21f4b812", "entity_id": 100001, "entity_type": "server", "nickname": "NovaPlayer", "server": { "app": { "id": 2400, "name": "Example Shooter", "steam_id": 111111, "url": "example-shooter" }, "game": 111111, "icon": null, "id": 100001, "name": "Example Arena" }, "user": { "avatar": "8f14e45f-e9a1-4f4d-a9f3-6d7b0d4a2c18.webp", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [ { "id": "100000000000000001", "name": "demo_user", "type": "discord", "url": "https://discord.com/users/100000000000000001" }, { "id": "76561198000000001", "name": "NovaPlayer", "type": "steam", "url": "https://steamcommunity.com/profiles/76561198000000001" } ] }, "claimed_at": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "security": [] } }, "/votes/{vote_id}/claim": { "post": { "operationId": "claimVote", "summary": "Acknowledge vote processing", "description": "Marks a vote as processed. Available to the server or project owner.", "security": [ { "AccountAPIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "vote_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteClaimResult" }, "example": { "response": { "success": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Missing, invalid, expired or revoked credential." }, "403": { "description": "Missing API key scope, restricted account or entity ownership." }, "404": { "description": "Unknown vote or invalid entity association." }, "429": { "description": "Account claim quota exceeded: 12 000 per minute. Honor Retry-After." } } } }, "/users/{id}": { "get": { "operationId": "getPublicUser", "summary": "User profile", "description": "Returns user profile data.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "id", "in": "path", "required": true, "description": "Account ID.", "schema": { "type": "string", "format": "uuid", "example": "ef57cc6f-f068-11ef-a5bf-d00d12c6f2dd" } } ], "responses": { "200": { "description": "User profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResult" }, "example": { "response": { "avatar": "447f9470-325b-4e0a-ada0-f4f1659ef805.png", "id": 1, "username": "GAMEMONITORING", "banner": "469ebf64-206c-4374-a742-7730ea227f95.webp", "connections": [ { "account_id": "76561197960287930", "account_level": 1, "id": 220354, "name": "Rabscuttle", "platform": { "icon": null, "id": 3, "name": "Steam", "url": "steam" } } ], "created": 1435235037, "last_online": 1793734264, "uuid": "ef57cc6f-f068-11ef-a5bf-d00d12c6f2dd" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "User not found." } } } }, "/users/verify-code": { "post": { "operationId": "verifyUserCode", "summary": "Verify account ownership", "description": "To verify ownership of a GAMEMONITORING account, the user gets a code under [Integration](/settings/integration). The code is valid for 5 minutes from issuance. If verification succeeds, the API returns the ID of the account that the code was issued for and marks the code as used.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "description": "One-time account verification code. The code is case-insensitive.", "pattern": "^\\s*[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}(?:-[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}){2}\\s*$", "example": "7KMD-P9RX-3WHT" } } } } } }, "responses": { "200": { "description": "The stable GAMEMONITORING account ID.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "response" ], "properties": { "response": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } }, "example": { "response": { "id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "description": "Invalid request or code format." }, "404": { "description": "Unknown, expired or already redeemed code." }, "429": { "description": "Too many requests." }, "503": { "description": "A required service is temporarily unavailable." } } } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP status code." }, "message": { "type": "string", "description": "Error message in the API language. The wording may vary; use the status code for handling errors." }, "data": { "description": "Additional error details, when available." } } } } }, "Server": { "type": "object", "properties": { "add_date": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix timestamp in seconds (UTC)." }, "app": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "steam_id": { "description": "Steam App ID of the game. Use this as game_steam_id when searching servers.", "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, { "type": "null" } ] }, "url": { "type": "string" } }, "additionalProperties": {} }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connect": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "game": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hide_address": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "hide_query": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "icon": { "type": [ "string", "null" ] }, "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "ip": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "last_update": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix timestamp in seconds (UTC)." }, "map": { "type": [ "string", "null" ] }, "maxplayers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ] }, "numplayers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "official": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "points": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "port": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "private": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pve": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pvp": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "request": { "type": [ "string", "null" ] }, "secured": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "steam_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, { "type": "null" } ], "description": "Retain string identifiers as strings to avoid losing precision." }, "version": { "type": [ "string", "null" ] }, "votes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "wipe": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix timestamp in seconds (UTC)." }, "ban_reason": { "type": [ "string", "null" ] }, "banned": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "boosts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bots": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "city": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Server description stored as a JSON-encoded block list." }, "disabled_modules": { "type": "array", "items": { "type": "string" } }, "gamemode": { "type": [ "string", "null" ] }, "hidden": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "last_offline": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix timestamp in seconds (UTC)." }, "last_online": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix timestamp in seconds (UTC)." }, "list_hidden": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "map_url": { "type": [ "string", "null" ] }, "mods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} } }, "next_wipe": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix timestamp in seconds (UTC)." }, "parked": { "type": "boolean" }, "position_game": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "wipe_period": { "type": [ "string", "null" ] } }, "required": [ "id", "parked" ], "additionalProperties": {} }, "ServerEnvelope": { "type": "object", "required": [ "response" ], "properties": { "response": { "$ref": "#/components/schemas/Server", "description": "Successful responses wrap the result in response. Lists may be arrays or objects with items; see the schema for this operation." } } }, "UserProfileResult": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object", "required": [ "id", "uuid", "username", "avatar", "banner", "created", "last_online" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "Numeric profile ID." }, "uuid": { "type": "string", "format": "uuid", "description": "Account ID." }, "username": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "banner": { "type": [ "string", "null" ] }, "created": { "type": [ "integer", "null" ] }, "last_online": { "type": [ "integer", "null" ] }, "connections": { "type": "array", "items": { "type": "object", "required": [ "id", "account_id", "account_level", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "account_id": { "type": "string" }, "account_level": { "type": [ "number", "null" ] }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "object", "null" ], "required": [ "id", "name", "icon", "url" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } } } } } } } } }, "ServerCreateResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "connect": { "type": [ "string", "null" ] }, "game": { "type": [ "integer", "null" ] }, "id": { "type": "integer", "minimum": 1 }, "name": { "type": [ "string", "null" ] }, "request": { "type": [ "string", "null" ] }, "status": { "type": [ "boolean", "null" ] } }, "required": [ "connect", "game", "id", "name", "request", "status" ] } }, "required": [ "response" ] }, "ServerPlayersResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "description": "If the session history query returns no players, `items` contains the full player list from the latest server poll, if available.", "type": "array", "items": { "type": "object", "properties": { "avatar": { "type": "string" }, "created": { "type": [ "number", "string", "null" ] }, "last_online": { "type": [ "number", "string", "null" ] }, "last_session_time": { "type": "number" }, "name": { "type": [ "number", "string", "null" ] }, "user": { "type": [ "object", "null" ], "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "username": { "type": [ "string", "null" ] } }, "required": [ "avatar", "last_session_time", "username" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "ServerPostsResult": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "response" ] }, "ServerPlayerStatsResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "avg_players": { "type": "number" }, "date": { "type": "number" }, "maps": { "type": "array", "items": { "type": "string" } }, "max_players": { "type": "number" }, "min_players": { "type": "number" }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "avg_players", "date", "maps", "max_players", "min_players", "x", "y" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "ProjectPlayerStatsResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "avg_players": { "type": "number" }, "date": { "type": "number" }, "max_players": { "type": "number" }, "min_players": { "type": "number" }, "x": { "type": "number" } }, "required": [ "avg_players", "date", "max_players", "min_players", "x" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "VoteDetailsEnvelope": { "type": "object", "properties": { "response": { "$ref": "#/components/schemas/VoteDetails" } } }, "VoteDetails": { "type": "object", "properties": { "id": { "type": "string", "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" }, "entity_id": { "type": "number", "description": "ID of the entity that received the vote.", "example": 1 }, "entity_type": { "type": "string", "description": "Type of the entity that received the vote.", "enum": [ "server", "project" ], "example": "server" }, "nickname": { "type": [ "string", "null" ], "example": "PlayerName" }, "created_at": { "type": "number", "example": 1710000000 }, "expires_at": { "type": "number", "example": 1710086400 }, "server": { "type": [ "object", "null" ], "description": "Present for `server` votes.", "properties": { "id": { "type": [ "number", "string", "null" ], "example": 1 }, "name": { "type": [ "string", "null" ], "example": "Public Server" }, "icon": { "type": [ "string", "null" ] }, "game": { "type": [ "number", "null" ], "example": 730 } } }, "project": { "type": [ "object", "null" ], "description": "Present for `project` votes.", "properties": { "id": { "type": "number", "example": 1 } } }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "number", "string", "null" ] }, "uuid": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] } } }, "webhook": { "type": [ "object", "null" ], "description": "Present only when the requester can view webhook delivery details.", "properties": { "attempted_at": { "type": [ "number", "null" ] }, "event_id": { "type": [ "string", "null" ] }, "event_type": { "type": [ "string", "null" ], "enum": [ "server.vote", "project.vote", null ], "example": "project.vote" }, "is_test": { "type": [ "boolean", "null" ] }, "request_body": { "type": [ "object", "null" ] }, "response_body": {}, "response_code": { "type": [ "number", "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "delivered", "failed", "no_result", "pending", null ] }, "url": { "type": [ "string", "null" ] } } }, "claimed_at": { "type": [ "integer", "null" ], "description": "Processing acknowledgement time in Unix seconds; null means unclaimed.", "example": null } } }, "VoteClaimResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } }, "required": [ "response" ] } }, "parameters": { "ApiVersion": { "name": "v", "in": "query", "required": false, "description": "API version. Omit v to use the lowest supported version. Specify v=1.0.0 to keep the documented contract. Invalid, repeated or unsupported values return HTTP 400.", "schema": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$", "const": "1.0.0" } }, "created": { "name": "created", "in": "query", "description": "Filter by the exact creation time in Unix seconds. With no date filters, the query covers all retained votes.", "schema": { "type": "integer", "example": 1800000000 } }, "created__gt": { "name": "created__gt", "in": "query", "description": "Creation time, Unix seconds >", "schema": { "type": "integer", "example": 1800000000 } }, "created__gte": { "name": "created__gte", "in": "query", "description": "Creation time, Unix seconds ≥", "schema": { "type": "integer", "example": 1800000000 } }, "created__lt": { "name": "created__lt", "in": "query", "description": "Creation time, Unix seconds <", "schema": { "type": "integer", "example": 1800000000 } }, "created__lte": { "name": "created__lte", "in": "query", "description": "Creation time, Unix seconds ≤", "schema": { "type": "integer", "example": 1800000000 } }, "expire": { "name": "expire", "in": "query", "description": "Expiration time, Unix seconds", "schema": { "type": "integer", "example": 1800000000 } }, "expire__gt": { "name": "expire__gt", "in": "query", "description": "Expiration time, Unix seconds >", "schema": { "type": "integer", "example": 1800000000 } }, "expire__gte": { "name": "expire__gte", "in": "query", "description": "Expiration time, Unix seconds ≥", "schema": { "type": "integer", "example": 1800000000 } }, "expire__lt": { "name": "expire__lt", "in": "query", "description": "Expiration time, Unix seconds <", "schema": { "type": "integer", "example": 1800000000 } }, "expire__lte": { "name": "expire__lte", "in": "query", "description": "Expiration time, Unix seconds ≤", "schema": { "type": "integer", "example": 1800000000 } }, "claimed": { "name": "claimed", "in": "query", "description": "Processing status: 0 unprocessed, 1 processed; all by default", "schema": { "type": "integer", "enum": [ 0, 1 ], "example": 0 } }, "limit": { "name": "limit", "in": "query", "description": "Number of items from 1 to 1000, default 100", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100 } }, "offset": { "name": "offset", "in": "query", "description": "Number of items to skip, minimum 0, default 0", "schema": { "type": "integer", "minimum": 0, "default": 0, "example": 0 } }, "order": { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "asc" } }, "sort": { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created", "expire" ], "default": "created", "example": "created" } }, "nickname": { "name": "nickname", "in": "query", "description": "Search by voter nickname fragments, 3 to 255 characters", "schema": { "type": "string", "minLength": 3, "maxLength": 255, "example": "Player" } }, "server_id": { "name": "server_id", "in": "query", "schema": { "type": "integer", "example": 42 } }, "entity_type": { "name": "entity_type", "in": "query", "schema": { "type": "string", "enum": [ "server", "project" ], "example": "server" } }, "webhook_status": { "name": "webhook_status", "in": "query", "schema": { "type": "string", "enum": [ "delivered", "failed", "no_result", "pending" ], "example": "failed" } }, "period": { "name": "period", "in": "query", "description": "Period based on vote creation time, all retained history by default", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "example": "30d" } } }, "securitySchemes": { "AccountAPIKey": { "type": "http", "scheme": "bearer", "description": "Account API key: 43 base64url characters without a prefix. Claim requires votes:claim scope plus current ownership. Send only in Authorization: Bearer ." } }, "responses": { "BadRequest": { "description": "Invalid parameters or JSON body. Check types, required fields and allowed ranges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 400, "message": "Invalid request parameters." } } } } }, "Forbidden": { "description": "Access denied: the address is blocked or the project is not public.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 403, "message": "Access denied." } } } } }, "ServiceUnavailable": { "description": "The service is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 503, "message": "Service temporarily unavailable." } } } } }, "QueryTimeout": { "description": "The query exceeded its time limit. Retry later or narrow the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 504, "message": "Query timed out." } } } } }, "NotFound": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 404, "message": "Resource not found." } } } } }, "UnexpectedError": { "description": "An unexpected server error. The error object contains the actual status code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 500, "message": "Internal server error." } } } } } } }, "servers": [ { "url": "https://api.gamemonitoring.net" } ] } ``` https://gamemonitoring.net/developers/docs/api.md --- # GAMEMONITORING MCP MCP (Model Context Protocol) gives agents access to GAMEMONITORING games, servers, online status, and player counts. All tools are read-only. Public access requires no account or API key. ## Connect an agent For manual setup, select Streamable HTTP and paste the URL. Cursor and VS Code offer direct installation. Command-line clients have ready-to-copy commands. ```text https://api.gamemonitoring.net/mcp ``` ### Codex ```bash codex mcp add gamemonitoring --url 'https://api.gamemonitoring.net/mcp' ``` ### Claude Code ```bash claude mcp add --scope user --transport http gamemonitoring 'https://api.gamemonitoring.net/mcp' ``` ### Gemini CLI ```bash gemini mcp add --scope user --transport http gamemonitoring 'https://api.gamemonitoring.net/mcp' ``` ### MCP JSON ```json { "mcpServers": { "gamemonitoring": { "url": "https://api.gamemonitoring.net/mcp" } } } ``` ### Example prompt for an agent ```text Use GAMEMONITORING to find the three Rust servers with the most players online. Show each server address and player count. ``` ## MCP tools Start with search_games. Pass the returned steam_id as game_steam_id to search, filter, or count servers. To get server details, use the GAMEMONITORING server ID returned by search_servers. ### search_games Finds games by name, slug, or Steam App ID. Returns steam_id, name, slug, and server and player counts. ```json { "name": "Rust", "limit": 1 } ``` ### get_server_filters Lists maps, versions, countries, languages, game modes, and other filters. Pass game_steam_id for a specific game or an empty object for shared filters. ```json { "game_steam_id": 252490 } ``` ### search_servers Finds servers by game and filters. Supports sorting, limit from 1 to 100, and offset. Include the game to narrow the search. ```json { "game_steam_id": 252490, "status": "online", "sort": "numplayers", "limit": 3 } ``` ### get_server Returns public details and current status for a numeric server_id. ```json { "server_id": 1 } ``` ### get_server_list_metadata Counts all matching servers, online servers, and online players using the same filters as server search. ```json { "game_steam_id": 252490, "status": "online" } ``` ## Data format On a successful tools/call, result.structuredContent contains the data. result.content includes a text representation and a link to the underlying REST request. Protocol errors appear in the top-level error field. On a tool error, result.isError is true, even with HTTP 200. Look for details in result.structuredContent.error when available. If a search times out, narrow it by game or other filters. https://gamemonitoring.net/developers/docs/mcp.md --- # Webhook {#webhook} Webhook sends a GAMEMONITORING event to your system after an action on the platform. It is a regular `POST` request with a JSON body, so a website, panel, or game service can react automatically. If you are setting up vote rewards, connect the Webhook with this guide first, then use the dedicated flow: [Vote rewards](https://gamemonitoring.net/developers/docs/webhook/vote#flow). ## Connection {#connect} This setup links a GAMEMONITORING project to your handler and provides a signing token for verifying incoming requests. 1. Open [My projects](https://gamemonitoring.net/projects/my), create a project or select an existing one, then go to Webhook settings. 2. Create a public HTTPS endpoint that accepts `POST` with `Content-Type: application/json` and does not redirect requests. 3. In Webhook settings, enter the full handler URL, for example `https://panel.example.com/gamemonitoring-webhook`, and save it. 4. Copy the signing token from the same block and add it to your handler script. 5. In the handler, verify `signature`, process the required `event_type`, and return a successful `2xx` response only after the event has been processed. For local testing, you can run the handler on your computer and expose it through a public HTTPS URL. Use [ngrok](https://ngrok.com) or another tunneling service, then enter the generated public URL in Webhook settings. After setup, send a test Webhook from the interface and check the delivery status. For the example URL, your server must accept `POST` on `/gamemonitoring-webhook`. If the test fails, use the handler response as the first clue: `401` means a signature error, `403` or an HTML verification page usually points to WAF or bot protection, and timeout means the URL is unreachable from the internet or responds too slowly. ## Handler Requirements {#handler-requirements} - The URL must be reachable from the internet. Local addresses, private networks, and URLs with a login or password are not suitable. - HTTPS is recommended for production. HTTP is supported, but it protects data in transit less effectively. - The handler must accept the `POST` method and a JSON body without redirects. - Return `2xx` only after your system has processed the event. Usually `204 No Content` is enough. - If the event cannot be processed safely, return an error code. `3xx`, `4xx`, `5xx`, timeout, and connection errors are treated as failed delivery. - If you use a firewall, bot protection, or an allowlist, add [GAMEMONITORING IP addresses](https://gamemonitoring.net/developers/docs/ips) to exceptions. - Do not return tokens, stack traces, SQL errors, or other internal details in the response body. The handler response is shown in the interface, so the error text must be safe and understandable. ## Event Data {#event-data} Every Webhook arrives with a JSON body and base fields: - `event_type` — the event that must be processed. - `event_id` — unique event ID. Use it together with `event_type` for idempotency and duplicate-delivery protection. - `is_test` — marks a test delivery from the interface. - `signature` — signature of the event body. **Webhook event example** ```json { "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "event_type": "example.event", "is_test": false, "signature": "0ac4c97a5d934599dbd78985c4bcbb6926e77b4809d2be56333b1b25f638f064" } ``` How to read this example: `event_type` shows which event must be processed; `event_id` is needed for idempotency before changing state; `is_test: true` means a technical delivery check; `signature` is not business data and is used only to authenticate the request. Processing logic depends on `event_type`. For `server.vote` and `project.vote`, use the dedicated flow: [Vote rewards](https://gamemonitoring.net/developers/docs/webhook/vote#flow). If `is_test` is `true`, verify the signature and return `2xx`, but do not change balances, issue items, or run production operations. ## Handler Response Example {#response-example} Finish each incoming event with one clear result: - `204 No Content` — the signature is valid, and the event was processed or safely skipped. Return the same response for a test delivery and for an event that has already been processed. - `400 Bad Request` — required fields are missing. This means a handler bug or an unexpected request body; do not run business logic. - `401 Unauthorized` — the signature is invalid. Do not make API requests, do not change the database, and do not issue rewards. - `500 Internal Server Error` — your database, queue, or internal system is temporarily unavailable. Delivery remains failed and can be retried after the cause is fixed. For example, if the handler received the event, verified the signature, stored `event_type` + `event_id`, and processed the event, it can return `204`. If the database is unavailable and the event cannot be stored, return `500` so delivery is not marked successful too early. ## Signature Verification {#signature} The signature is stored in the `signature` field. Verify it before any business logic, API request, or database change. To verify it, take all event body fields except `signature`, sort keys alphabetically, and build a `key=value` string joined with `&`. Boolean values are written as `true` or `false`. **Signing string** ```text event_id=9824cabb-2203-437e-9b6c-aba43dde3e4b&event_type=example.event&is_test=false ``` For the example above, the signing string is built only from `event_id`, `event_type`, and `is_test`. Then calculate `HMAC-SHA256` with the signing token from Webhook settings and compare it with `signature` from the request. Precomputed signatures in the examples use the demo token `paste-webhook-token-here`. In your handler, use the token from Webhook settings. In your handler: - build the signing string from sorted keys; - calculate `HMAC-SHA256` with the signing token; - compare the result with `signature` using a constant-time helper: `hash_equals` in PHP, `timingSafeEqual` in Node.js, or `compare_digest` in Python; - return `401` when the signature is invalid. ## Step 1. Basic Handler {#minimal-handler} Start with a handler that can accept any Webhook: it reads JSON, verifies `signature`, handles a test delivery, validates base fields, and returns `204`. At this step, the handler only confirms that delivery is accepted correctly. Add event-specific logic after this base path works. ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // At this point the webhook is trusted. Add event-specific logic here. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); // 204 tells GAMEMONITORING that the delivery was accepted successfully. http_response_code(204); ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // At this point the webhook is trusted. Add event-specific logic here. console.log('Accepted webhook event ' + eventType + ' #' + eventId) // 204 tells GAMEMONITORING that the delivery was accepted successfully. return res.sendStatus(204) }) app.listen(3000) ``` ### Python ```python import hashlib import hmac from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # At this point the webhook is trusted. Add event-specific logic here. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) # 204 tells GAMEMONITORING that the delivery was accepted successfully. return '', 204 ``` ## Step 2. Add Deduplication {#deduplication} Webhook uses at-least-once delivery: the same event can arrive more than once. Before the handler changes your system state, make that operation idempotent by `event_type` + `event_id`. First, create a table that stores the pair `event_type` and `event_id` with a unique key. If the record already exists, the event has already been processed. **Processed Webhook events table** ```sql CREATE TABLE gamemonitoring_webhooks ( event_type varchar(64) NOT NULL, event_id varchar(100) NOT NULL, created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (event_type, event_id) ); ``` Then extend the basic handler: after signature verification and base field validation, store `event_type` + `event_id` and perform state changes in the same transaction. ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // At this point the webhook is trusted. Deduplicate it before event-specific logic. $pdo = null; try { // Add your local database connection for deduplication and event-specific work. $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]); // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. $pdo->beginTransaction(); // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)'); $deduplicate->execute([$eventType, $eventId]); // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if ($deduplicate->rowCount() === 0) { $pdo->commit(); http_response_code(204); exit; } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. // Commit only after deduplication and event-specific work both succeed. $pdo->commit(); // Log only newly processed real events after the transaction succeeds. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); http_response_code(204); } catch (Throwable $error) { // Roll back partial database work so the event can be retried safely. if ($pdo instanceof PDO && $pdo->inTransaction()) { $pdo->rollBack(); } // 500 keeps the delivery failed instead of marking unfinished work as done. http_response_code(500); } ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const mysql = require('mysql2/promise') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // Add your local database connection for deduplication and event-specific work. const db = mysql.createPool({ database: 'game', host: '127.0.0.1', password: 'password', user: 'game', }) // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', async (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // At this point the webhook is trusted. Deduplicate it before event-specific logic. let connection try { connection = await db.getConnection() // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. await connection.beginTransaction() // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. const [deduplicate] = await connection.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)', [eventType, eventId], ) // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if (deduplicate.affectedRows === 0) { await connection.commit() return res.sendStatus(204) } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. // Commit only after deduplication and event-specific work both succeed. await connection.commit() // Log only newly processed real events after the transaction succeeds. console.log('Accepted webhook event ' + eventType + ' #' + eventId) return res.sendStatus(204) } catch (error) { // Roll back partial database work so the event can be retried safely. if (connection) { await connection.rollback() } // 500 keeps the delivery failed instead of marking unfinished work as done. return res.sendStatus(500) } finally { // Return the connection to the pool. if (connection) { connection.release() } } }) app.listen(3000) ``` ### Python ```python import hashlib import hmac import pymysql from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' # Add your local database connection for deduplication and event-specific work. db_config = { 'database': 'game', 'host': '127.0.0.1', 'password': 'password', 'user': 'game', } def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # At this point the webhook is trusted. Deduplicate it before event-specific logic. connection = None try: connection = pymysql.connect(**db_config) connection.begin() # Keep deduplication and the real state change in one transaction. # If any step fails, return 500 so the delivery can be retried. with connection.cursor() as cursor: # Store the event once. This requires the table to have a unique key # on (event_type, event_id). Duplicate deliveries affect zero rows. cursor.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)', (event_type, event_id), ) # The event was already processed earlier. Return success without # changing state again, because duplicate delivery is expected. if cursor.rowcount == 0: connection.commit() return '', 204 # Add event-specific database changes here. Keep them after the # deduplication insert and inside this same transaction. # Commit only after deduplication and event-specific work both succeed. connection.commit() # Log only newly processed real events after the transaction succeeds. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) return '', 204 except Exception: # Roll back partial database work so the event can be retried safely. if connection: connection.rollback() # 500 keeps the delivery failed instead of marking unfinished work as done. abort(500) finally: # Close the database connection. if connection: connection.close() ``` Do not use nickname, user ID, or server ID as the deduplication key: one user can trigger different events or repeat an allowed action later. The key must be `event_type` + `event_id`. Example: the handler changed your system state, but the connection broke before GAMEMONITORING received `204`. Later the delivery is retried, and the same event arrives again. Your handler must find the already stored `event_type` + `event_id`, skip the repeated state change, and return `204`. If the handler temporarily cannot process an event, return an error response. After the cause is fixed, delivery can be retried from the interface when retry is available for that event. ## Tests and Resend {#tests-resend} A test delivery (`is_test: true`) checks the URL, signature, and HTTP response of the handler. The handler must follow the same processing path: read JSON, verify `signature`, recognize `is_test`, and return a successful `2xx` response. A test event must not change balances, inventory, roles, subscriptions, or other production data. A technical log and a `204` response are enough for a test. If delivery fails, the interface shows the status, HTTP status code, and handler response. After fixing the cause, a failed delivery can be resent when retry is available for that event. https://gamemonitoring.net/developers/docs/webhook.md --- # Vote Rewards {#vote-rewards} Vote rewards use the `server.vote` and `project.vote` Webhook events: the handler receives the event, fetches vote data through the API, finds the user in your system, and issues the reward only once. First configure the [project Webhook](https://gamemonitoring.net/developers/docs/webhook#connect) and [signature](https://gamemonitoring.net/developers/docs/webhook#signature) verification. Vote data is requested through [GET /votes/:vote_id](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/__GET). ## How the Flow Works {#flow} 1. Receive the Webhook event and [verify signature](https://gamemonitoring.net/developers/docs/webhook#signature). If [is_test](https://gamemonitoring.net/developers/docs/webhook#tests-resend) is `true`, return `204` without fetching the vote and without issuing a reward. 2. Make sure `event_type` is `server.vote` or `project.vote`. 3. Use `event_id` as the vote ID. 4. Fetch vote data through [GET /votes/:vote_id](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/__GET) and find the player in your system. 5. In one transaction, apply [duplicate-processing protection](https://gamemonitoring.net/developers/docs/webhook#deduplication) by `event_type` + `event_id` and issue the reward only for a new event. 6. If the reward cannot be issued safely, return an error response. After fixing the cause, [retry delivery](https://gamemonitoring.net/developers/docs/webhook#tests-resend) from the interface. ## Reward Example {#reward-example} Suppose player `PlayerName` voted for the server with ID `1`, and your system must add `100` coins. 1. GAMEMONITORING sends a Webhook with `event_type: server.vote` and `event_id: 9824cabb-2203-437e-9b6c-aba43dde3e4b`. 2. The handler [verifies signature](https://gamemonitoring.net/developers/docs/webhook#signature). If the signature is invalid, it returns `401` and stops. 3. The handler requests `GET /votes/9824cabb-2203-437e-9b6c-aba43dde3e4b`, receives nickname, server, and user data, and finds the local account. 4. In a transaction, the handler stores `event_type` + `event_id` for [duplicate-processing protection](https://gamemonitoring.net/developers/docs/webhook#deduplication). 5. For a new event, the handler adds `100` coins in the same transaction. 6. On repeated delivery, the handler finds the already stored event, does not issue the reward again, and returns `204`. The same flow also works for items, roles, VIP time, promo codes, or work queued in an internal system. ## Vote Event {#vote-event} When a server receives a vote, GAMEMONITORING sends `server.vote`; when a project receives a vote, it sends `project.vote`. The event body contains only delivery data: `event_type`, `event_id`, `is_test`, and `signature`. Full vote data must be requested separately. **Event example** ```json { "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "event_type": "server.vote", "is_test": false, "signature": "ae83b8aba88a3a9ab3b97b1f6d65664da5628a9cb64d56d5132807bca5472e4f" } ``` In either event, `event_id` is the vote ID. Do not use the Webhook body as the source for nickname, entity, or user data: those values come from the API. ## Fetch Vote Data {#fetch-vote} Use `event_id` as `vote_id` and request the vote data through [GET /votes/:vote_id](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/__GET): **Vote data request** ```bash curl -sS "https://api.gamemonitoring.net/votes/9824cabb-2203-437e-9b6c-aba43dde3e4b" ``` For reward delivery, use `response.entity_type` and `response.entity_id` to distinguish the target. A server vote also contains `response.server`; a project vote contains `response.project`. Both types contain `response.nickname` and public `response.user` data. How to use the fields: `response.nickname` helps find the account in your database, `response.entity_type` and `response.entity_id` select the reward rule, and `response.user.id` can be stored in the reward log as the GAMEMONITORING user ID that voted. Always verify that `server.vote` returned `entity_type: server` and `project.vote` returned `entity_type: project`. If the API is temporarily unavailable or returns an unexpected response, do not issue a reward without verification. Return an error code, fix the cause, and [retry delivery](https://gamemonitoring.net/developers/docs/webhook#tests-resend) from the interface. ## Step 3. Vote Reward Handler {#complete-example} The example continues the basic handler: it verifies the signature, fetches vote data, prevents duplicate processing, and applies the reward in one transaction. Replace the user table name, balance field, and player lookup rule with your system structure. Before running the example, configure the [project Webhook](https://gamemonitoring.net/developers/docs/webhook#connect), check [GET /votes/:vote_id](https://gamemonitoring.net/developers/docs/api/votes/:vote_id/__GET), and replace the SQL user update queries with your account model. ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // This reward handler processes server and project vote events. if (!in_array($eventType, ['server.vote', 'project.vote'], true)) { http_response_code(204); exit; } // At this point the webhook is trusted. Load vote data before opening a database transaction. $pdo = null; try { // Load full vote data by event_id. Nickname, entity, and user data are not // in the webhook body. Return 500 if the API cannot confirm the vote. $voteUrl = $apiUrl . '/votes/' . rawurlencode($eventId); $voteContext = stream_context_create(['http' => ['timeout' => 5]]); $voteBody = @file_get_contents($voteUrl, false, $voteContext); if ($voteBody === false) { throw new RuntimeException('Vote API request failed'); } $voteResponse = json_decode($voteBody, true) ?: []; $vote = $voteResponse['response'] ?? null; // Do not issue a reward when the vote response is missing a concrete nickname. if (!is_array($vote) || !isset($vote['nickname']) || !is_string($vote['nickname'])) { throw new RuntimeException('Vote API response does not include nickname'); } // Verify that the API entity matches the event before changing the account. $expectedEntityType = $eventType === 'project.vote' ? 'project' : 'server'; if (($vote['entity_type'] ?? '') !== $expectedEntityType) { throw new RuntimeException('Vote entity type does not match event type'); } // Use vote nickname to update the local account. The entity id is available in // vote.entity_id and in either vote.server.id or vote.project.id. $nickname = trim($vote['nickname']); if ($nickname === '') { throw new RuntimeException('Vote nickname is empty'); } // Add your local database connection for deduplication and event-specific work. $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]); // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. $pdo->beginTransaction(); // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)'); $deduplicate->execute([$eventType, $eventId]); // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if ($deduplicate->rowCount() === 0) { $pdo->commit(); http_response_code(204); exit; } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. $balance = $pdo->prepare('UPDATE users SET balance = balance + ? WHERE nickname = ?'); $balance->execute([$rewardAmount, $nickname]); // Commit only after deduplication and event-specific work both succeed. $pdo->commit(); // Log only newly processed real events after the transaction succeeds. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); http_response_code(204); } catch (Throwable $error) { // Roll back partial database work so the event can be retried safely. if ($pdo instanceof PDO && $pdo->inTransaction()) { $pdo->rollBack(); } // 500 keeps the delivery failed instead of marking unfinished work as done. http_response_code(500); } ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const mysql = require('mysql2/promise') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // Add the GAMEMONITORING API URL and reward settings for vote events. const apiUrl = 'https://api.gamemonitoring.net' const rewardAmount = '1.00' // Add your local database connection for deduplication and event-specific work. const db = mysql.createPool({ database: 'game', host: '127.0.0.1', password: 'password', user: 'game', }) // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', async (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // This reward handler processes server and project vote events. if (!['server.vote', 'project.vote'].includes(eventType)) { return res.sendStatus(204) } // At this point the webhook is trusted. Load vote data before opening a database transaction. let connection try { // Load full vote data by event_id. Nickname, entity, and user data are not // in the webhook body. Return 500 if the API cannot confirm the vote. const voteUrl = apiUrl + '/votes/' + encodeURIComponent(eventId) const voteResponse = await fetch(voteUrl, { signal: AbortSignal.timeout(5000) }) if (!voteResponse.ok) { throw new Error('Vote API request failed') } const voteBody = await voteResponse.json() const vote = voteBody.response // Do not issue a reward when the vote response is missing a concrete nickname. if (!vote || typeof vote.nickname !== 'string') { throw new Error('Vote API response does not include nickname') } // Verify that the API entity matches the event before changing the account. const expectedEntityType = eventType === 'project.vote' ? 'project' : 'server' if (vote.entity_type !== expectedEntityType) { throw new Error('Vote entity type does not match event type') } // Use vote nickname to update the local account. The entity id is available in // vote.entity_id and in either vote.server.id or vote.project.id. const nickname = vote.nickname.trim() if (!nickname) { throw new Error('Vote nickname is empty') } connection = await db.getConnection() // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. await connection.beginTransaction() // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. const [deduplicate] = await connection.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)', [eventType, eventId], ) // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if (deduplicate.affectedRows === 0) { await connection.commit() return res.sendStatus(204) } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. await connection.execute('UPDATE users SET balance = balance + ? WHERE nickname = ?', [rewardAmount, nickname]) // Commit only after deduplication and event-specific work both succeed. await connection.commit() // Log only newly processed real events after the transaction succeeds. console.log('Accepted webhook event ' + eventType + ' #' + eventId) return res.sendStatus(204) } catch (error) { // Roll back partial database work so the event can be retried safely. if (connection) { await connection.rollback() } // 500 keeps the delivery failed instead of marking unfinished work as done. return res.sendStatus(500) } finally { // Return the connection to the pool. if (connection) { connection.release() } } }) app.listen(3000) ``` ### Python ```python import hashlib import hmac import pymysql import requests from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' # Add the GAMEMONITORING API URL and reward settings for vote events. api_url = 'https://api.gamemonitoring.net' reward_amount = '1.00' # Add your local database connection for deduplication and event-specific work. db_config = { 'database': 'game', 'host': '127.0.0.1', 'password': 'password', 'user': 'game', } def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # This reward handler processes server and project vote events. if event_type not in ('server.vote', 'project.vote'): return '', 204 # At this point the webhook is trusted. Load vote data before opening a database transaction. connection = None try: # Load full vote data by event_id. Nickname, entity, and user data # are not in the webhook body. Return 500 if the API cannot confirm the vote. vote_url = f"{api_url}/votes/{event_id}" response = requests.get(vote_url, timeout=5) if not response.ok: raise RuntimeError('Vote API request failed') vote = response.json().get('response') # Do not issue a reward when the vote response is missing a concrete nickname. if not isinstance(vote, dict) or not isinstance(vote.get('nickname'), str): raise RuntimeError('Vote API response does not include nickname') # Verify that the API entity matches the event before changing the account. expected_entity_type = 'project' if event_type == 'project.vote' else 'server' if vote.get('entity_type') != expected_entity_type: raise RuntimeError('Vote entity type does not match event type') # Use vote nickname to update the local account. The entity id is available in # vote.entity_id and in either vote.server.id or vote.project.id. nickname = vote['nickname'].strip() if not nickname: raise RuntimeError('Vote nickname is empty') connection = pymysql.connect(**db_config) connection.begin() # Keep deduplication and the real state change in one transaction. # If any step fails, return 500 so the delivery can be retried. with connection.cursor() as cursor: # Store the event once. This requires the table to have a unique key # on (event_type, event_id). Duplicate deliveries affect zero rows. cursor.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)', (event_type, event_id), ) # The event was already processed earlier. Return success without # changing state again, because duplicate delivery is expected. if cursor.rowcount == 0: connection.commit() return '', 204 # Add event-specific database changes here. Keep them after the # deduplication insert and inside this same transaction. cursor.execute('UPDATE users SET balance = balance + %s WHERE nickname = %s', (reward_amount, nickname)) # Commit only after deduplication and event-specific work both succeed. connection.commit() # Log only newly processed real events after the transaction succeeds. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) return '', 204 except Exception: # Roll back partial database work so the event can be retried safely. if connection: connection.rollback() # 500 keeps the delivery failed instead of marking unfinished work as done. abort(500) finally: # Close the database connection. if connection: connection.close() ``` https://gamemonitoring.net/developers/docs/webhook/vote.md --- # System IP addresses GAMEMONITORING uses these IP addresses to check game servers and [deliver Webhook requests](https://gamemonitoring.net/developers/docs/webhook#connect) to your system. Add them to your allowlist if your server, website, WAF, CDN, or bot protection limits incoming requests. ## When to add them {#when-needed} - the game server accepts requests only from allowed addresses; - the [Webhook handler](https://gamemonitoring.net/developers/docs/webhook#handler-requirements) is protected by a firewall, WAF, or Cloudflare; - bot protection blocks automated requests; - the hosting provider asks for IP addresses for network rules. ## Usage example {#usage-example} Webhook example: your handler is located at `https://panel.example.com/gamemonitoring-webhook` and the domain is protected by Cloudflare. Add GAMEMONITORING IP addresses to the allowlist for this domain or exact path so Cloudflare does not show a challenge and does not block [Webhook `POST` requests](https://gamemonitoring.net/developers/docs/webhook#handler-requirements). Game server example: the firewall allows the query port only from trusted addresses. Add GAMEMONITORING IP addresses to the rule for the query port, otherwise monitoring will not be able to check online status and server state reliably. ## Configure the allowlist {#allowlist} Pass the IP addresses from the list above to your system administrator or hosting provider. The rule must allow incoming requests from these addresses to your game server or Webhook handler. If the rule is path-based, limit it to the required endpoint, for example `/gamemonitoring-webhook`. If the rule is port-based, specify only the game query port or the web-server port that receives Webhook. ## Verify after configuration {#verification} After changing the rules, send a test request or [test Webhook](https://gamemonitoring.net/developers/docs/webhook#tests-resend) and check that the request is no longer blocked. If the check fails, inspect firewall, WAF, or Cloudflare logs. The logs should show source IP, request path, and block reason. That tells you whether the domain, path, port, or rule order is missing. ## Cloudflare configuration {#cloudflare} If the Webhook handler is behind Cloudflare, add GAMEMONITORING IP addresses to a rule that skips WAF checks for these requests: 1. Log in to the Cloudflare dashboard. 2. Select the required domain. 3. Open **Security**. 4. Select **WAF**. 5. Open **Custom rules**. 6. Click **Create rule**. 7. Set a clear rule name, for example **Allow GAMEMONITORING**. 8. In **Field**, select **IP Source Address**. 9. In **Operator**, select **is in**. 10. In **Value**, add the IP addresses from the list above. 11. In **Choose action**, select **Skip**. 12. In **WAF components to skip**, select the checks that block requests to your handler. 13. In **Select order**, select **First**. 14. Click **Deploy**. If requests are still blocked after setup, check firewall or Cloudflare logs and make sure the rule applies to the correct domain and handler path. ```http GET https://api.gamemonitoring.net/pages/system/ips ``` https://gamemonitoring.net/developers/docs/ips.md