Documentation
Client and API
API overview
Updated 2026-11-03
API overview
The API is versioned under /api/v1, authenticated with Sanctum, and covered by an OpenAPI parity test.
Conventions
- JSON requests and responses.
- Guest-first flow; register/login upgrade the guest account.
- Validation errors return
422with field messages. - Domain errors return
422with amessage. - Ownership is enforced by policies and scoped queries.
- Mutating endpoints are throttled.
- Idempotency keys protect rewards and submissions.
- Results are server-authoritative; no answer or seed leakage.
Areas
| Area | Examples |
|---|---|
| Auth | register, login, logout, logout-all, verification, password reset, 2FA |
| Catalog | list, search, advanced filters, options, profiles |
| Collection | list, card, favorite, admit, sell, life actions, slots |
| Races | create, lineup, calculate, result, history, reward cards |
| Economy | wallet, packs, premium exchange, rewarded center |
| Trading | listings, offers, auctions, followed listings |
| Social | clubs, messages, moderation, reports, sanctions, appeals |
| Quiz | sets, submit, mastery review, error monsters |
| Control | HMAC-signed health, version, license, theme sync and maintenance (feature-gated) |
| Manual | published manual sections |
Health
GET /api/v1/health
Contract
The OpenAPI document is codebase/api/OPENAPI.yaml. The parity test fails when a route and the document disagree. Regenerate or update the document with every contract change.
Security
- Tokens expire (
AUTH_TOKEN_TTL_DAYS). - Suspended or banned players are blocked.
- Pending-deletion accounts are blocked.
- Sensitive actions are audited.
- The control API requires an HMAC signature, a timestamp window and a nonce.