Quickstart

Raw markdown source view for LLM workflows.

---
title: Quickstart
description: Get your first successful request/response cycle with the GameQuery API.
---

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.

```bash
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

```bash
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:

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

```bash
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`.