API documentation

1. Sign in, then generate a key from API keys in the header — see Authentication.
2. Create a lobby — see POST /api-v1-create-lobby. The response includes the lobby's join code.
3. Fetch progress and results any time — see GET /api-v1-lobby-results.

All endpoints are Supabase Edge Functions under:

https://hjhlsvjmxadedijpofvg.supabase.co/functions/v1/api-v1-<endpoint>

Every request needs Authorization: Bearer <key>. The raw key (vk_live_...) is shown exactly once when generated — copy it immediately, only its hash is stored afterward. A key is tied to your account and inherits your normal lobby-creation limits (including the 10-lobby cap — see Errors).

Revoked or unrecognized keys get a 401:

{ "error": "INVALID_API_KEY" }

Each endpoint has its own bucket, separate from the web app's own limits:

Exceeding a limit returns 429 with {"error": "RATE_LIMITED"}. Lobby creation also has a second, stricter limit underneath the API's own bucket: your account can create at most 5 lobbies per 10 minutes (the same limit the web app's creation form is subject to) — whichever limit is hit first returns RATE_LIMITED.

Confirms a key is valid. No side effects, no rate limit.

curl https://hjhlsvjmxadedijpofvg.supabase.co/functions/v1/api-v1-me \
  -H "Authorization: Bearer vk_live_..."

{ "ok": true, "userId": "3f06f4ea-d868-4ce2-9308-b979b0797979" }

Creates a lobby, identical in shape to what the web form's "Create lobby" button sends.

curl -X POST https://hjhlsvjmxadedijpofvg.supabase.co/functions/v1/api-v1-create-lobby \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Where should we eat lunch?",
    "questions": [
      { "title": "Pick a spot", "type": "choice", "options": ["Tacos", "Sushi", "Salad"] }
    ],
    "voterCap": 30,
    "ballotMode": "anonymous",
    "tallyVisibility": "live"
  }'

Body fields

Question object fields

Example: mixed question types

A 3-question survey combining all 3 types — one ranked-choice question, one multi-select ("choose up to N") question, and one free-text question:

{
  "title": "Team offsite planning",
  "questions": [
    { "title": "Rank these venues", "type": "ranked", "options": ["Beach house", "Mountain cabin", "City loft"] },
    { "title": "Which activities interest you?", "type": "choice", "options": ["Hiking", "Cooking class", "Board games", "Spa"], "maxSelections": 2 },
    { "title": "Anything else we should plan for?", "type": "text" }
  ],
  "voterCap": 25,
  "ballotMode": "open",
  "tallyVisibility": "hidden"
}

The response includes the generated code voters use to join at votero.app/vote/<code>.

Reads progress/tally/ballot-detail for a lobby you created— a foreign or nonexistent code both return 404, deliberately indistinguishable, so a wrong code can't be used to probe whether someone else's code exists.

Query parameters

curl "https://hjhlsvjmxadedijpofvg.supabase.co/functions/v1/api-v1-lobby-results?code=7S8XDH6C" \
  -H "Authorization: Bearer vk_live_..."

{
  "progress": { "joined": 12, "cap": 30, "completedCount": 10 },
  "tally": [
    {
      "questionId": "...",
      "questionTitle": "Pick a spot",
      "type": "choice",
      "tally": [{ "optionId": "...", "count": 7 }, { "optionId": "...", "count": 3 }]
    }
  ],
  "ballotDetail": null
}

tally is null until the lobby is closed or tally visibility is live. ballotDetail is only populated for open-ballot lobbies.

All errors are {"error": "SOME_CODE"} with a matching HTTP status:

Field-length/range violations (e.g. voterCap outside 1–10,000, a title over 200 characters) return a 400 with a raw database error message rather than one of the codes above — validate against the limits in the parameter tables above to avoid hitting these.

• No vote-casting or lobby-joining via API key — that represents an end-user voting, not a server acting on their behalf.
• No standalone lobby-read endpoint — create-lobby's response already has everything a caller who just created a lobby needs.
• No integration (Zapier, HubSpot, etc.) — this is the raw API; where to point it is a separate, later decision.