GameQuery API

Back to Docs Page

Raw markdown source view for LLM workflows.

---
title: GameQuery API
description: Query live game server state through one REST contract, with a normalised payload shape across every supported game.
---

GameQuery answers server queries from continuously refreshed state. A distributed
worker swarm probes tracked servers on a rolling schedule, so your request reads
recent data instead of opening a UDP query and waiting for a game server that may
never answer.

## API host

- Production base URL: `https://api.gamequery.dev`
- Current stable version: `v1`
- Public paths are prefixed with `/v1`. Nothing else on that host is routed.

<Callout type="warn">
  The API is **not** served from `https://gamequery.dev`. That host answers
  unknown paths with the website's HTML shell and a `200`, so a client pointed
  there fails on JSON parsing rather than on a clear `404`.
</Callout>

## The whole public surface

| Method | Path | Auth | Purpose |
| --- | --- | --- | --- |
| `GET` | `/v1/get/games` | No | The supported game catalogue, as `{ id, name }`. |
| `POST` | `/v1/post/fetch` | Yes | Live payloads for up to 1000 addresses, grouped by game. |

Two routes. There is no single-server `GET` route, no `/v1/post/add`, and no
WebSocket or streaming interface.

## What you can do

- Read the game catalogue (334 entries at the time of writing) and use the `id`
  values as `game_id`.
- Fetch live payloads for many servers in one batched request.
- Register new `game_id + ip:port` pairs simply by asking for them: valid unknown
  pairs are auto-inserted and start being probed.
- Read per-server updater metadata (`_updater`) so a client can tell fresh data
  from last-known data.
- Collect per-row validation diagnostics from `_meta.invalid_servers` without the
  whole batch failing.

<Cards>
  <Card title="Quickstart" href="/docs/quickstart" description="From API key to a parsed payload." />
  <Card title="Authentication" href="/docs/authentication" description="The three headers, quotas and whitelist rules." />
  <Card title="POST /v1/post/fetch" href="/docs/endpoints/post-fetch" description="The full request and response contract." />
  <Card title="Data Freshness" href="/docs/data-freshness" description="How _updater, _stale and auto-insert behave." />
  <Card title="Errors and Limits" href="/docs/errors-and-limits" description="Every status code and error code the API emits." />
  <Card title="LLM Integration" href="/docs/llms-full" description="A drop-in prompt and tool definition for AI agents." />
</Cards>