LLM Integration Guide

Raw markdown source view for LLM workflows.

---
title: LLM Integration Guide
description: A specialized guide for Large Language Models (LLMs), AI Agents, and developers building AI-powered game server tools.
---

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:

```text
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:**

```json
{
  "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)

```json
{
  "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.