api_routes

Using the API

Every product endpoint lives under /v1/. The rendered API reference documents each one: its path, parameters, request and response bodies, and status codes. That reference is built from openapi.yaml at the repository root, which is the source of truth.

This page does not repeat the endpoint list. It covers what the reference assumes you already have: how to authenticate, the base URL, and the rules that hold across every route.

Base URL

All routes are relative to your deployment's host plus the /v1 prefix. On the local development stack that is http://localhost:8080/v1. Against a hosted deployment, use your own host in place of localhost. The /v1 prefix pins the API version, and the wire contract under it is stable; the Go and C# SDKs are generated from the same openapi.yaml.

Authentication headers

Two headers identify a request, and most routes need both. The API key says which tenant or project is calling. The session token says which signed-in player the call acts for.

• Authorization: Bearer <api_key> identifies the tenant or project. Send it on every request.
• X-Session-Token: <jwt> identifies the signed-in player. Send it on calls that act for a player.

Some keys carry a narrower scope. Server-tier routes need a fleet- or server-scoped key rather than a normal client key, and a publishable client key cannot reach them. See Core Concepts for how keys, scopes, and session tokens fit together, and Authentication and Players for how a player gets a session token.

Error shape

Every error returns application/problem+json (RFC 7807) with the same shape:

{
  "status": 409,
  "title": "ticket_already_active",
  "detail": "player already holds an active ticket",
  "instance": "/v1/matchmaker/tickets"
}

status is the HTTP code, title is a stable short slug you can branch on, and detail is a human-readable message. Validation failures add an errors array that points at the offending fields. The feature guides call out the titles you meet most.

Rate limits and quotas

• Requests are rate limited. Over the limit returns 429 with a Retry-After header. Back off and retry after the delay.
• A saturated server returns 503 with Retry-After rather than queuing indefinitely. The default per-request deadline is 15 seconds.
• A player holds at most one active matchmaking ticket per project. A second create returns 409 ticket_already_active.
• A single storage object value has a platform cap, 1 MiB by default, which a tenant tier can raise or lower.
• Concurrent WebSocket connections are capped per player and per tenant.
• Per-tenant limits such as open sessions and stored objects come from the tenant's tier class. See Quotas, Tiers, and Entitlements. A default self-hosted deployment runs uncapped.

For anything about a specific endpoint, read the API reference or openapi.yaml.