API reference

{
  "name": "Board Election 2026",
  "slug": "board-election-2026",
  "status": "revealed",              // draft | open | closed | revealed
  "candidates": [{ "index": 0, "label": "Alice" }, ...],
  "ballot_open": "2026-03-01T09:00:00Z",
  "ballot_close": "2026-03-08T09:00:00Z",
  "reveal_at": "2026-03-08T10:00:00Z",
  "drand_round": 18452031,
  "drand_chain_hash": "52db9ba7...",
  "ballot_count": 47,
  "voter_count": 60,
  "revealed_at": "2026-03-08T10:00:04Z",
  "results": {
    "winner": "Alice",
    "winner_index": 0,
    "is_tie": false,
    "totals": [{ "candidate": "Alice", "index": 0, "votes": 20 }, ...],
    "total_ballots": 47,
    "spoiled": 0,
    "drand_round": 18452031,
    "drand_signature": "8f2c..."
  }
}

results is null until the reveal. There is no early partial tally to fetch, because no party has one.

{ "status": "revealed",
  "revealed_at": "2026-03-08T10:00:04Z",
  "results": { ... } }

{
  "event_slug": "board-election-2026",
  "num_candidates": 3,
  "merkle_root": "a41f...",
  "ballots": [
    { "ballot_id": "0d9c...", "encrypted_vote": "base64...",
      "nullifier": "5b2e...", "merkle_index": 0 }, ...
  ],
  "registrations": [
    { "voter_pub_key": "hex...", "blinded_credential": "base64...",
      "challenge": "hex...", "voter_signature": "hex..." }, ...
  ]
}

Available while voting is open, since sealed ballots reveal nothing. Two invariants are worth asserting in your own code: ballots.length <= registrations.length, and every nullifier appearing exactly once.

The board plus everything needed to check it independently: drand_public_key, drand_round, merkle_root, and published_results — the last so a verifier can hold our announcement against its own recomputed tally rather than printing two sets of numbers and leaving you to compare them.

# the verifier will fetch this for you
$ zerovote-verify --slug board-election-2026 --api https://api.zerovote.app

# or pin it yourself, and pair it with the beacon for that round
$ curl -s https://api.zerovote.app/v/board-election-2026/snapshot > election.json
$ zerovote-verify --snapshot election.json --beacon beacon.json

{ "live": [...], "upcoming_reveals": [...], "recent_results": [...] }

{ "email": "you@example.com", "password": "..." }
→ { "token": "jwt", "user_id": "..." }

Nothing cryptographic is stored against the account. There is no key to lose and no blob to decrypt, which is what makes the alternative below possible.

{ "id_token": "eyJ..." }        // from Google Identity Services
→ { "token": "jwt", "user_id": "..." }

The token is verified against Google's published signing keys, with the audience pinned to this deployment's client id and email_verified required. There is no separate signup: the account exists once Google has vouched for the address. Returns 400 when the server has no GOOGLE_CLIENT_ID configured.

{ "name": "Board Election 2026",
  "candidates": ["Alice", "Bruno", "Chidi"],   // 2–100, ≤200 chars, distinct
  "voters": ["a@example.com", "b@example.com"],
  "group_ids": [],
  "ballot_open":  "2026-03-01T09:00:00Z",      // ≥ now − 5min
  "ballot_close": "2026-03-08T09:00:00Z",      // > ballot_open
  "reveal_at":    "2026-03-08T10:00:00Z",      // > ballot_close
  "is_public": true,
  "publish_now": true,                         // false → draft, nothing mailed
  "webhook_url": "https://you.example.com/hook" }

Ballots are single-choice: voters pick exactly one candidate, so two options sharing a label are rejected — the tally is reported per option and nothing downstream could say which of the two won. The reveal time can never change afterwards, since the ballots are encrypted to that drand round.

Omitting publish_now mails the invites as part of the same call. Passing false leaves the election in draft: nothing is mailed, no voter slots exist yet, and the roster comes back unmasked so it can be checked. Publish it with the call below, or delete it while it is still a draft.

Creates one voter slot per address, mails every invite, and moves the election to open. Irreversible, and refused on an election that is already published. Invites name the organizer only when their address is verified.

Sends the invite again to the address already on that slot, which cannot be changed. slot_id comes from the roster and opens nothing on its own. Refused once the voter has collected their credential, since the old link would no longer work.

Drafts only. Once invites are out the election is a matter of public record, and deleting it would let an organizer erase a count people were relying on — so this returns 400 for anything past draft.

Returns ballot_count, registered_count, voter_count, the Merkle root, and per-voter slots carrying a slot_id and a masked address — full addresses only while the election is a draft, so the roster can be proofread before anything is sent. registered means a credential was collected — not that a ballot was cast.

{ "event_id": "...", "event_name": "...", "event_slug": "...",
  "candidates": [...], "num_candidates": 3,
  "blind_signing_public_key": "...",
  "drand_public_key": "...", "drand_round": 18452031,
  "ballot_close": "...", "already_registered": false,
  "voter_pub_key": "hex" }       // absent if the invite has no key yet

{ "public_key": "hex" }         // Ed25519, 32 bytes
→ 204

Skip this when voter_pub_keyis already present. Voters don't need an account, so an invite usually arrives with no key on it and the client generates one. The claim is idempotent for the same key and returns 409 for a different one: whoever claimed the slot keeps it, because allowing a takeover would let anyone who saw the link lock out the real voter.

→ { "challenge": "hex", "expires_at": "..." }

{ "challenge": "hex",
  "signature": "hex",             // see the domain note below
  "blinded_credential": "base64" }
→ { "blind_signature": "base64" }

Exactly one credential is issued per voter, ever. There is no reissue, so persist the unblinded credential before you attempt to submit — a client that loses it between these two calls has stranded that voter permanently.

{ "credential": "base64",
  "signature": "base64",          // unblinded RSA signature
  "msg_randomizer": "base64",     // present for the randomized variant
  "encrypted_vote": "base64" }    // tlock(choice_index, drand_pk, round)
→ { "ballot_id": "...", "merkle_index": 12, "merkle_root": "...",
    "merkle_proof": { ... }, "leaf_hash": "..." }

This request is deliberately unauthenticated — a bearer token here would recreate exactly the link blind signing exists to destroy. 409 means the credential was already spent.

The response is the voter's receipt, and it is the only copy. We cannot look it up again, because we do not know which ballot is theirs. Store it client-side and verify merkle_proof before telling anyone the vote succeeded.