Gray Zone Warfare API Reference

01 · First request

Quick start

All routes are read-only and return JSON. Use /api/v1 for new integrations; the unversioned /api prefix remains available for compatibility. Every file in the repository’s data/ directory becomes a dataset endpoint automatically.

curl https://gzw-data.dev/api/v1/weapons

const response = await fetch("https://gzw-data.dev/api/v1/weapons");
const payload = await response.json();

import requests
payload = requests.get("https://gzw-data.dev/api/v1/weapons").json()

Official client

Use the JavaScript / TypeScript package

Skip handwritten fetch code with the zero-dependency client for Node.js 18+, browsers, JavaScript and TypeScript.

npm install @zoniboy/gzw-data-client

import { GzwDataClient } from "@zoniboy/gzw-data-client";

const gzw = new GzwDataClient();
const weapons = await gzw.dataset("weapons").list();
console.log(weapons.data);

View package on npm ↗

01.1 · Single record

Get one record

Dataset records can be fetched directly by exact ID:

curl https://gzw-data.dev/api/v1/weapons/ak-12

The JavaScript client exposes the same route through dataset.get(id).

01.2 · Schema metadata

Dataset metadata

Inspect generated field metadata without downloading a full dataset:

curl https://gzw-data.dev/api/v1/metadata/weapons

The response includes item count, observed fields, detected types, optional/nullable flags and a stable example value. Use /api/v1/metadata for the lightweight registry or /api/v1/metadata?full=true for detailed metadata for every dataset.

02 · Route catalog

Endpoints

— datasets are currently exposed. This list is populated from the live API, so new scraper categories appear here automatically.

Loading endpoint catalog…

03 · Querying

Filters, search & pagination

Query any dataset with the same small set of composable parameters. Filters match string fields and can be combined with pagination.

QUERY?field=valueFilter by any string field, for example ?type=Keycard

QUERY?search=akFull-text search across the record fields

QUERY?sort=name:ascSort by a field with asc or desc

QUERY?page=2&per_page=20Paginate results; per_page defaults to 50 and caps at 500

QUERY?all=trueReturn all filtered records without pagination

https://gzw-data.dev/api/v1/keys?type=Keycard&search=alpha&page=1&per_page=20

04 · Contract

Response format

Paginated routes return a stable envelope. Unpaginated responses omit the pagination fields while preserving data, count, source and timestamp. The /api/v1/spec document exposes generated dataset schemas under components.schemas, based on the same metadata as /api/v1/metadata.

{
  "data": [ ... ],
  "count": 10,
  "page": 1,
  "perPage": 50,
  "total": 2141,
  "totalPages": 43,
  "source": "GZW Data API",
  "timestamp": "2026-08-24T09:00:00.000Z"
}

05 · Operations

Limits & cache

Rate limit

Best-effort: 100 requests/minute/IP. The sliding-window counter lives in the memory of each warm Vercel function instance, so it is not a strict global quota across all instances. Responses expose X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A blocked request returns 429 with Retry-After. Cache responses and respect the retry delay.

Cache behavior

Data endpoints send Cache-Control: public, max-age=300. Cache in your client when you can; the wiki-backed data is refreshed by the weekly scraper.

Build on the GZW index.