HTTP API

Platform

Two surfaces that never share authentication: `/v1/game` for dedicated servers, `/v1/admin` for the dashboard.

Authentication

A dedicated server holds an API key and exchanges a provider ticket for a short-lived player token. The token is opaque and checked against the platform on every request, so a ban applies immediately rather than whenever the token happens to expire.

sign a player in, then act as them

curl -X POST https://api.raidstate.com/v1/game/sessions \
  -H "Authorization: Bearer $EXTRACTOR_API_KEY" \
  -d '{"provider":"steam","ticket":"…","scopes":["player:read"]}'

# -> {"player":{...},"tokens":{"access_token":"…"}}

Requesting a scope does not grant it

Narrowing intersects with what the session would have been granted anyway. A caller asking for a scope it was never going to get does not receive it by asking.

Game endpoints

Method	Path	What it does
POST	/v1/game/sessions	Exchange a provider ticket for a player token
GET	/v1/game/players/me/summary	Player, containers and contents in one call
POST	/v1/game/containers/ensure	Find or create a container, with its contents
GET	/v1/game/containers/{id}	One container
POST	/v1/game/inventory/grant	Put an item in
POST	/v1/game/inventory/move	Relocate an instance, possibly across containers
POST	/v1/game/inventory/consume	Remove some or all of a stack
POST	/v1/game/inventory/split	Divide a stack
POST	/v1/game/inventory/merge	Combine two stacks
POST	/v1/game/inventory/transaction	A batch of intents, all-or-nothing
POST	/v1/game/currency/transfer	Move currency between players
GET	/v1/game/catalog/items	What items exist in this environment

Idempotency

Every mutation accepts an Idempotency-Key header. Replaying a request with the same key returns the original outcome instead of performing it again, which is what makes a retry safe over a connection that drops mid-raid.

Errors

Failures are RFC 9457 problem documents. The type is a stable URI, so a client can branch on the kind of failure without matching on message text.

{
  "type": "https://errors.raidstate.com/slot_occupied",
  "title": "Position occupied",
  "detail": "those cells are already occupied",
  "status": 409,
  "instance": "a86c39d2-…"
}

The instance is the request id, and it appears in the platform's own logs — quote it and support can find the exact request.

The full specification

api/openapi.yaml in the repository covers all 59 operations, and a test walks the routing table in both directions: an endpoint cannot be added without appearing in the spec, and the spec cannot describe one that does not exist.

Concepts

API keys