LLM Integration Guide

This document is optimized for both human developers and for ingestion by LLMs (GPT, Claude, Gemini, and similar models) to interact with the active GameQuery API contract.

For system prompts (LLM instructions)

If you are configuring an AI agent to use GameQuery, include these instructions:

You are a GameQuery API assistant.
1. BASE_URL: https://api.gamequery.dev/v1
2. AUTH: Requires X-API-Token, X-API-Token-Type (FREE/PRO), and X-API-Token-Email headers.
3. CATALOG: Use GET /get/games to discover valid game_id values.
4. ENDPOINT: Use POST /post/fetch for runtime queries.
5. FORMAT: Servers must be "ip:port" strings grouped by game_id.
6. BATCHING: Maximum 1000 server addresses per request.
7. VALIDATION: Check _meta.invalid_servers in every response.

API reference for LLMs

Discover game IDs

Endpoint: GET /v1/get/games

Behavior:

• Returns game catalog entries in { id, name } format.
• Does not require auth headers.
• Served from a Redis-backed 24h cache and returned gzip-compressed.

Query live server data

Endpoint: POST /v1/post/fetch

Payload schema:

{
  "servers": [
    {
      "game_id": "string",
      "servers": ["string (ip:port)"]
    }
  ]
}

Behavior:

• Returns current payloads keyed by ip:port.
• Auto-inserts valid unknown (game_id, server) pairs.
• Reports invalid rows in _meta.invalid_servers.

Function calling / tool definition (JSON schema)

{
  "name": "query_game_servers",
  "description": "Fetch live status for game servers using GameQuery API",
  "parameters": {
    "type": "object",
    "properties": {
      "game_id": {
        "type": "string",
        "description": "The GameQuery game identifier (for example 'minecraft' or 'rust')"
      },
      "addresses": {
        "type": "array",
        "items": { "type": "string" },
        "description": "List of 'ip:port' strings"
      }
    },
    "required": ["game_id", "addresses"]
  }
}

Best practices for AI agents

1. Context management: Responses can be large. Summarize long server lists for chat output.
2. Error handling: If 429, explain quota limits. If 401, verify auth headers and package type.
3. Validation: Validate ip:port before request and surface _meta.invalid_servers to users.

Example request flow (LLM generated)

Input: "Check if the rust server at 12.34.56.78:28015 is online."

Action:

1. Call /v1/get/games and confirm rust exists as a valid id.
2. Call /v1/post/fetch with game_id: "rust" and servers: ["12.34.56.78:28015"].
3. Parse returned payload for status, players, and metadata.