API

HTTP contracts for TideGuard. Base URL is your Worker hostname (local: http://localhost:8787).

For first deploy and /admin setup, see getting-started.md. For the wizard and branding control room, see admin.md.

Machine-readable contract: openapi.yaml (OpenAPI 3.1).

Errors

All JSON error responses use:

{
  "error": {
    "code": "bad_request",
    "message": "Human readable message",
    "details": {}
  }
}

Endpoints

`GET /health`

Liveness check.

`POST /join`

Enter a queue.

{ "queue": "product-launch", "visitorId": "optional-id" }

200 — admitted immediately (includes accessToken; sets HttpOnly tg_access + tg_ticket)
202 — waiting (sets HttpOnly tg_ticket only)

Every successful join sets cookie tg_ticket (visitor ownership proof). /status, /leave, and /heartbeat require that cookie to match the visitor id and queue.

Waiting responses include admissionMode (queue | lottery), while waiting nextCheckAt (absolute unix ms, second-aligned timeslot) and nextPollAfterMs (compat delay hint). Depth fields (waiting, ahead, behind, lotteryOdds) are included only when branding showWaitingCount (“Show place in line”) is enabled. Public join/status never expose pause, health, opensAt, or capacity.

Queue Mode — position (1-based FIFO), optional ahead / behind / #X of Y, estimatedWaitSeconds, nextCheckAt
Lottery Mode — position omitted, estimatedWaitSeconds, optional lotteryOdds / waiting, plus nextCheckAt

Check-in timeslots keep Durable Object status load near a fixed 750 RPS budget (periodSec = max(5, ceil(waiting/750))). Front-of-line waiters stay on a 5s period. Early /status before nextCheckAt is read-only (does not renew liveness). The built-in waiting room (full page and ?embed=1) schedules on nextCheckAt. Fixed intervals via WAITING_ROOM_POLL_INTERVAL_MS / WAITING_ROOM_HEARTBEAT_INTERVAL_MS are advanced and not recommended.

If a valid tg_ticket cookie is already present for the queue, join resumes that visitor and ignores a conflicting body visitorId (same-browser multi-tab). When the waiting-row cap is reached, /join returns 503 queue_full.

`GET /status?queue=…&id=…`

Current visitor status. Requires cookie tg_ticket for that visitor/queue. When status is admitted and click-to-enter is satisfied, response includes accessToken and sets HttpOnly tg_access. Same field rules as /join (no ops fields; depth only if showWaitingCount). Waiting /status renews liveness only when the timeslot is due.

`POST /leave`

Requires tg_ticket.

{ "queue": "product-launch", "visitorId": "…" }

`POST /heartbeat`

Keep a waiting visitor alive. Requires tg_ticket. Usually unnecessary for the built-in waiting room (status renews liveness); kept for custom clients and fixed-interval overrides.

{ "queue": "product-launch", "visitorId": "…" }

`POST /enter`

Confirm entry after admission when click-to-enter is enabled. Requires tg_ticket.

{ "queue": "product-launch", "visitorId": "…" }

Marks the visitor as entered
Returns accessToken and sets HttpOnly tg_access
409 if the visitor is not admitted yet
Unconfirmed admits expire after branding admitHoldSeconds (server-side)

When click-to-enter is off, join/status issue the access token as soon as status is admitted (entered: true).

Redirect after admission

Waiting room destination order:

?return= on /wait (same-origin relative path)
Branding redirectUrl from /admin
/ if origin proxy is on, else /demo

See verifying-admission.md.

`POST /admit`

Operator-only: admit up to count waiters into open slots, ignoring the rate budget but still respecting capacity, opening time, manual pause, and health auto-pause. Selection follows the room’s admission mode (FIFO in Queue Mode, random in Lottery Mode).

Auth:

Admin session cookie tg_admin, or
Authorization: Bearer <TOKEN_SECRET>, or
X-TideGuard-Operator: <TOKEN_SECRET>

{ "queue": "product-launch", "count": 2 }

`POST /mode`

Operator-only: switch admission strategy for a queue at runtime.

{ "queue": "product-launch", "mode": "lottery" }

mode must be "queue" (FIFO line) or "lottery" (uniform random among waiters). Default comes from ADMISSION_MODE in Worker vars.

`POST /pause`

Operator-only: silent pause / resume. Visitors are not told; admissions stop while paused.

{ "queue": "product-launch", "paused": true }

`GET /metrics?queue=…`

Operator-only (same auth as /admit). Queue depth, capacity, ETA, pause state, opening time, effective admit rate, health snapshot, admissionMode, plus ops fields: entered, holding, openSlots, averageWaitSeconds, oldestWaitSeconds. Computed in the Durable Object (no KV write).

Admin UI also polls GET /api/admin/metrics every 5s (admin session) for the live metric strip and geo-block hit stats. The traffic chart uses GET /api/admin/traffic (server-backed ~15s buckets, ~24h retention; format=csv for export) — see analytics.md.

`POST /api/admin/pass`

Admin session only. Mints an admission cookie for this browser and returns { redirectTo } so operators can open the protected app without joining the queue. Does not consume a concurrent slot.

`PUT /api/admin/geo-block`

Admin session only. Temporary country block list (CF-IPCountry) with required TTL when enabling.

{ "enabled": true, "countriesText": "CN\\nRU", "ttlHours": 24 }

Cost estimate

GET /api/cost-estimate

Query params:

Param	Default	Meaning
`visitors`	`5000000`	Unique waiting-room visitors
`averageWaitSeconds`	`900`	Typical wait before admission
`pollingMode`	`adaptive`	`adaptive` (default timeslot) or `fixed` (advanced, not recommended)
`pollIntervalSeconds`	timeslot / `15`	Adaptive: `max(5, ceil(visitors/750))`; fixed status poll when `pollingMode=fixed`
`heartbeatIntervalSeconds`	`0` / `30`	Unused in adaptive; fixed heartbeat when `pollingMode=fixed`

Interactive UI: GET /cost (timeslot/adaptive by default; fixed intervals under advanced).

Admin

Queue limits

GET / PUT /api/admin/queue-limits — admin session. Read or set per-queue max waiting visitors (default 1000000, range 1…50_000_000). PUT body: { queue?, maxWaitingVisitors, previousMaxWaitingVisitors, confirmChanges: true } (A→B confirm; previousMaxWaitingVisitors must match the current value). When the cap is reached, public /join returns 503 queue_full.

`GET /admin`

React admin SPA (Mantine + Chart.js) from Workers Static Assets. First visit runs a setup wizard (claim with TOKEN_SECRET + username/password locks the account, then Cloudflare → Turnstile → queue/mode → branding). Later visits require username + password + Turnstile. Invite links use /admin?invite=…. The control room has a sticky event toolbar (rate, pause, force-admit, Pass queue), section tabs (Live, Admission, Branding, Access, Cloudflare, Team, System), branding preview, and Cloudflare zone controls.

Build assets with npm run build:admin before wrangler deploy.

Admin API

Method	Path	Auth	Notes
`GET`	`/api/admin/bootstrap`	public	Setup flags, version, `tosVersion` / `tosSummary` / `acceptedTosVersion`
`POST`	`/api/admin/claim`	`TOKEN_SECRET` bearer (once)	Requires `acceptedTosVersion` (= current); locks first admin + session
`POST`	`/api/admin/tos/accept`	session (stale ToS OK)	Requires `acceptedTosVersion` (= current); stamps that version on the user
`POST`	`/api/admin/setup/cloudflare/token-verify`	admin session	Validates API token and seals it in setup-pending (no zone write)

/admit, /mode, /pause, and /metrics accept either an admin session cookie or TOKEN_SECRET via Bearer / X-TideGuard-Operator.

Admitted visitors receive an HMAC-SHA256 token (also set as HttpOnly cookie tg_access):

base64url(payload).base64url(signature)

Claims:

Field	Meaning
`sub`	Visitor id
`queue`	Queue name
`iat`	Issued-at (unix seconds)
`exp`	Expiry (unix seconds)

Send tokens as:

Authorization: Bearer <token>, or
?accessToken=, or
cookie tg_access

Verification uses a timing-safe signature compare. Protected pages should call requireAdmission() (wired in the demo milestone).