# API REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`, generated from the route table (`npm run openapi`); this file covers conventions and per-resource notes. ## Conventions - Auth: `Authorization: Bearer ` (opaque, one per device; `POST /auth/login` or `/auth/signup` issues one, `POST /auth/logout` and `DELETE /auth/tokens/:id` revoke). No cookies. - Every response is an object with `serverTime` (integer ms since epoch, server clock). Clients compute countdowns from the offset. - Errors: `{ serverTime, error: { code, message, details } }`. Clients switch on `code`. All codes: `x-error-codes` in openapi.json. - Mutating POSTs accept `Idempotency-Key` (8-64 chars `A-Za-z0-9_.:-`); a replay returns the stored response with `Idempotent-Replay: true`; the same key with a different request is `idempotency_key_reuse`. - Lists are cursor-paginated: `?after=&limit=`, response `next` is the cursor or `null`. - Rate limits: per IP, per token, stricter on login/signup. `429 rate_limited` with `Retry-After`. - The client never sends computed amounts, only intents. The server recomputes everything with `public/js/rules.js`. ## Resources (stage 0-2) | Route | Purpose | | ----- | ------- | | `POST /auth/signup`, `POST /auth/login` | account + token (signup also founds the capital POP) | | `GET /me` | user, operators (per world), POPs | | `GET /towns/:id` | full POP state: resources `{amount, rate, cap}` at `serverTime`, power, buildings with the server's build plan, queue | | `POST /towns/:id/build {key}` | build/upgrade one level of a field (`f1..f18`) or an infrastructure building | | `DELETE /towns/:id/queue/:eventId` | cancel a running build, 80% refund | | `GET /map?x&y&r` | rural areas, incumbent sites, POPs in the viewport | | `GET /notifications?after&limit` | durable notification feed (build done, ...) | Later stages append their routes here and to the route table.