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", "turnstileToken": "optional-token" }

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 — the visitor’s next place/ETA update), nextPollAfterMs (compat delay hint), admissionOpen (whether the opening schedule allows admission), and opensAt (only while still scheduled closed). 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, 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 after the room is open. When opensAt is still in the future, nextCheckAt is deferred to a timeslot at or after opensAt (full-depth period, no front-band rush), so status polls do not run until admission can start. 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.

When Branding enables visitor Turnstile, a new browser must send turnstileToken. Invalid or missing challenges return 401; missing Turnstile configuration returns 503. A valid ticket resume skips the challenge. /status and /heartbeat never require Turnstile.

`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 <ADMIN_SECRET|TOKEN_SECRET>, or
X-TideGuard-Operator: <ADMIN_SECRET|TOKEN_SECRET>

Use ADMIN_SECRET when that Worker secret is set; otherwise TOKEN_SECRET. Visitor admission HMAC always uses 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) and missed-slot grace seconds (default 120, range 30…900). PUT body: { queue?, maxWaitingVisitors, previousMaxWaitingVisitors, missedSlotGraceSeconds, previousMissedSlotGraceSeconds, confirmChanges: true } (A→B confirm; previous values must match). When the waiting cap is reached, public /join returns 503 queue_full. Missed-slot grace is how long after a due nextCheckAt a silent waiter stays before expiry (never shorter than one check-in period).

`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 Bearer / X-TideGuard-Operator (ADMIN_SECRET when set, else TOKEN_SECRET).

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).