Quickstart

This flow is optimized for first-time integration and local testing.

1) Collect API credentials

From your dashboard, copy:

• X-API-Token
• X-API-Token-Type (FREE or PRO)
• X-API-Token-Email

Store them in environment variables.

export GQ_API_BASE_URL="https://api.gamequery.dev"
export GQ_API_VERSION="v1"
export GQ_API_TOKEN="your-token"
export GQ_API_TOKEN_TYPE="FREE"
export GQ_API_TOKEN_EMAIL="[email protected]"

2) Fetch valid game IDs

curl "$GQ_API_BASE_URL/$GQ_API_VERSION/get/games"

Use the id value exactly as returned.

The games list endpoint is backed by a Redis cache with a 24h TTL and served gzip-compressed.

3) Prepare your request payload

POST /v1/post/fetch accepts grouped server entries in this shape:

{
  "servers": [
    {
      "game_id": "minecraft",
      "servers": ["203.0.113.10:25565"]
    }
  ]
}

If game_id is invalid, the API reports it in _meta.invalid_servers.

4) Fetch live server payloads

curl -X POST "$GQ_API_BASE_URL/$GQ_API_VERSION/post/fetch" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: $GQ_API_TOKEN" \
  -H "X-API-Token-Type: $GQ_API_TOKEN_TYPE" \
  -H "X-API-Token-Email: $GQ_API_TOKEN_EMAIL" \
  -d '{
    "servers": [
      {
        "game_id": "minecraft",
        "servers": ["203.0.113.10:25565"]
      }
    ]
  }'

The response contains payloads keyed by ip:port plus a _meta object with insert and validation diagnostics.

To test v2 later, change only GQ_API_VERSION from v1 to v2 in non-production environments.

Operational limits

• Maximum 1000 server addresses per request.
• POST /v1/post/fetch requires Content-Type: application/json.
• Invalid game IDs and malformed addresses are reported in invalid_servers.