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, luck rating, and trophy case for an Instagram handle.

Added in v0.1.23-beta.0. Chromeless, shareable buyer stat card — optimized for screenshot and social sharing. Shows wins, losses, spots claimed, win rate, luck rating (actual vs. statistically expected win rate), and trophy case. Includes Open Graph / Twitter Card meta tags so the URL previews inline when posted to Instagram or other platforms.

Added in v0.1.23-beta.3. Downloadable PNG share card for a waffle. Rate-limited. Accepts a ?format= query parameter:

• story (default) — 1080×1920 vertical, ideal for Instagram Stories
• square — 1080×1080, ideal for feed posts

Card shows the waffle title, spot price, spots remaining, and the public claim URL. Generated with Inter font and Project Syrup branding; cached on disk per slug+format (invalidated by the regenerate endpoint). Returns Content-Type: image/png with Cache-Control: public, max-age=3600. Returns 404 for archived waffles. No auth required.

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 specific spots. Rate-limited.

{
  "waffle_id": "<uuid>",
  "spots": [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. Instagram handle is normalized server-side (lowercased, @ stripped).

Added in v0.1.21-beta.0. Claim count random available spots in a single transaction. Rate-limited via the same limiter as /api/claims.

{
  "waffle_id": "<uuid>",
  "count": 5,
  "instagram_handle": "dani_boo_glass"
}

Server selects count random spots under a row-level lock and claims them. Returns:

{
  "claimed_count": 5,
  "requested_count": 5,
  "spot_numbers": [3, 8, 14, 22, 29],
  "message": "Claimed 5 spots"
}

Partial fulfillment: if fewer spots are available than requested, the server claims as many as it can and returns claimed_count < requested_count with a message like "Claimed 3 of 5 requested spots". No client-side maximum cap is enforced — the server is authoritative.

Each claimed spot fires a separate WebSocket spot_update broadcast.

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

Full claim history for an Instagram handle across all waffles.

Added in v0.1.23-beta.0. Returns all computed buyer card data as JSON. Always returns 200 — unknown handles return zeroed stats rather than 404.

{
  "instagram_handle": "dani_boo_glass",
  "stats": { "total_wins": 3, "total_losses": 12, "total_spots_claimed": 47, ... },
  "win_rate": 0.0638,
  "expected_win_rate": 0.0421,
  "luck_rating": 0.0217,
  "trophies": ["Stanley Cup", "Mystery Box"],
  "waffle_history": [...]
}

luck_rating = actual win rate minus statistically expected win rate over completed waffles. Positive = luckier than expected; negative = unluckier.

trophies are item names extracted from double-quoted text in waffle titles (e.g. a title of Waffle — "Stanley Cup" yields "Stanley Cup").

Added in v0.1.23-beta.2. Returns the running app version. No authentication required.

{ "version": "v0.1.23-beta.3" }

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",
  "description": "Limited drop",
  "total_spots": 50,
  "spot_price": 5,
  "payment_methods": ["<payment-method-uuid>", "<payment-method-uuid>"],
  "item_count": 1,
  "image_url": "https://...",
  "instagram_media_links": ["https://www.instagram.com/p/..."]
}

item_count defaults to 1 if omitted. Set to 2–10 for multi-item waffles where you'll draw that many winners. Returns the created waffle with its generated slug.

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.

Set winner(s). Updated in v0.1.20 to accept an array — supply one entry per item.

{ "winning_spot_numbers": [17] }
// or for a multi-item waffle (item_count > 1):
{ "winning_spot_numbers": [17, 23, 42] }

Marks each listed spot as winner, marks all other paid spots as loser, populates the waffle's winning_instagram_handles array, and updates buyer stats. Spots must be distinct and currently paid. Fires a waffle_completed WebSocket broadcast.

Clear all winners on the waffle. Resets every winning spot to paid, restores loser spots to paid, recalculates buyer stats, and reverts the waffle to active. Fires a winner_cleared WebSocket broadcast.

Reassign winner(s) without clearing first. Same payload shape as /winner.

{ "winning_spot_numbers": [23] }
// or for multi-item:
{ "winning_spot_numbers": [23, 31, 44] }

Old winning spots not in the new selection revert to paid; new selections become winner; loser status is recomputed across all paid spots. Recalculates buyer stats. Fires a winner_changed WebSocket broadcast.

Added in v0.1.23-beta.3. Get the current share message and template selection for a waffle.

Added in v0.1.23-beta.3. Save a share message for a waffle. Both fields required together.

{ "template_id": "<uuid>", "message": "Grab your spots! 🧇\n{url}" }

Added in v0.1.23-beta.3. Render a template body with waffle data substituted. Returns the expanded message string for preview.

Added in v0.1.23-beta.3. Invalidate the cached PNG for this waffle (both story and square formats). The next request to /waffle/:slug/card.png will regenerate it.

List all message templates. Returns {"templates": [...]}.

Create a new template.

{ "name": "Standard Drop", "body": "Spots open! 🧇\nLink: {url}" }

Update a template's name or body. Same payload shape as POST.

Delete a template.

Set this template as the default. The default is pre-selected in the share message editor on the waffle manage page.

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 payment methods (active and inactive). Returns an array of PaymentMethod objects with id, type, display_name, handle_or_url, and is_active.

Create a new payment method.

{
  "type": "venmo",
  "display_name": "Venmo — @notfixingit",
  "handle_or_url": "@notfixingit"
}

Valid type values: venmo, paypal, cashapp, zelle. handle_or_url can be a raw handle (the public page will format the link based on type) or a full URL. New methods are is_active: true by default.

Update a payment method's display name, handle, or active status.

{ "display_name": "Venmo — Primary", "handle_or_url": "@notfixingit", "is_active": true }

All fields are optional — only the ones present are updated. Changes propagate to every waffle that references this method.

Soft-delete a payment method (sets is_active = false). The record is preserved so historical waffles still resolve. The method no longer appears in the multi-select on new or edited waffles. To reactivate, PATCH with {"is_active": true}.

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.