API Reference

Home page. Lists active waffles with live spot counts.

Full public waffle list.

Waffle detail page with live spot grid. This is the URL you share with buyers.

Public buyer stats page showing win/loss history for an Instagram handle.

Public about page. Authenticated admins see additional system information.

List all active (non-archived) waffles. Returns an array of waffle summary objects.

Get full waffle details by slug, including title, price, total spots, claimed/paid counts, and media links.

Download waffle spot list as CSV. Columns: spot number, status, claimed_by_handle. No auth required.

Get the full spot grid for a waffle. Returns all spots with number, status, and (if claimed) the Instagram handle.

Claim one or more spots. Rate-limited.

{
  "waffle_slug": "blue-wig-3",
  "spot_numbers": [4, 7, 12],
  "instagram_handle": "dani_boo_glass"
}

Returns the updated spot objects or an error if any spot is already taken. Transactionally safe — no double-claims possible.

Win/loss statistics for an Instagram handle. Returns total claims, wins, and losses.

Full claim history for an Instagram handle across all waffles.

Authenticate and receive a JWT.

{ "username": "admin", "password": "syrup" }

Returns { "token": "..." } on success. Sets a secure token cookie. Returns 401 on bad credentials; 429 after lockout threshold is exceeded.

Clears the session cookie. No body required.

Request a password reset token by username.

{ "username": "admin" }

Always returns 200 (does not reveal whether the username exists). A super_admin must retrieve the token and share it with the user out-of-band.

Reset password using a token.

{ "token": "...", "new_password": "..." }

Token is single-use and expires. Password must meet the password policy.

Returns the authenticated admin's profile: id, username, role, timezone, profile fields.

Update timezone preference.

{ "timezone": "America/New_York" }

Change your own password. Requires current password.

{ "current_password": "...", "new_password": "..." }

List waffles. Query param: ?archived=true for archived waffles, ?archived=false (default) for active.

Create a new waffle.

{
  "title": "Blue Wig #3",
  "price_per_spot": "25.00",
  "total_spots": 50,
  "media_links": ["https://www.instagram.com/p/..."]
}

Update waffle title, price, or media links. Spot count cannot be changed after creation.

Archive a waffle. Requires admin or higher.

Restore an archived waffle to active status.

Permanently delete a waffle and all its spots. Requires typing DELETE and providing current password as confirmation.

{ "confirmation": "DELETE", "password": "..." }

Requires admin or higher. Irreversible.

Enter the winning spot number.

{ "spot_number": 17 }

Marks the spot as winner, updates buyer stats for all paid spots.

Clear the current winner. Resets the winning spot to active; recalculates buyer stats.

Reassign the winner to a different spot.

{ "spot_number": 23 }

Recalculates buyer stats for all affected spots.

Mark a pending spot as paid. Broadcasts a WebSocket update to all connected clients.

Release a pending or paid spot back to available. Broadcasts a WebSocket update.

List all admin accounts with username, role, and active status.

Create a new admin account.

{ "username": "jane", "password": "...", "role": "admin" }

Valid roles: super_admin, admin, waffle_manager.

Update role. Demotions require current password confirmation.

{ "role": "waffle_manager", "current_password": "..." }

Reset another admin's password. The admin should change it on next login.

{ "new_password": "..." }

Deactivate an admin account. Requires current password.

{ "current_password": "..." }

Deactivated admins cannot log in. Their audit history is preserved. They can be reactivated.

Buyers with the most losses and no recent win, sorted by loss streak.

Buyers ranked by total paid spots across all waffles.

Waffles run, spots claimed, and payments received grouped by calendar month.

Time from waffle creation to last spot claimed, per waffle. Shows how quickly your drops sell out.

List audit log entries with pagination. Query params: ?page=1&per_page=50&admin_id=&action=&from=&to=

Get a single audit log entry by ID.

Export filtered audit log entries as CSV. Same filter params as the list endpoint.

List login history. Visibility is role-scoped:

• waffle_manager — own entries only
• admin — own + waffle_manager entries
• super_admin — all entries

Optional query param: ?admin_id= (super_admin only).

List all registered buyer handles (the users registry). Returns handle and first-seen timestamp.

Retrieve current system settings (WHOIS server, JWT expiry, retention periods, lockout config).

Update one or more system settings.

{
  "whois_server": "whois.pwhois.org",
  "jwt_expiry_hours": 24,
  "audit_log_retention_days": 90,
  "login_history_retention_days": 90
}

Connect to the real-time hub for a waffle. Replace :slug with the waffle slug. The client receives JSON messages whenever a spot changes state.

Returns 200 with {"status":"ok","db":"connected"} when healthy. Returns 503 if the database is unreachable.

Readiness probe for container orchestrators. Same response format as /health.