Skip to main content

​
GET /polls

Returns all polls in the current state. Response 
[
  {
    "poll_id": "referendum-2026-1",
    "poll_hash": "a3f9...",
    "question": "Should the proposal pass?",
    "options": ["yes", "no"],
    "voting_method": "yes_no",
    "start_time": 1700000000,
    "end_time": 1700086400,
    "status": "open",
    "created_at": 1699990000
  }
]

​
GET /polls/

Returns a single poll definition. Parameters
NameLocationDescription
poll_idpathThe unique poll identifier
Response 
{
  "poll_id": "referendum-2026-1",
  "poll_hash": "a3f9...",
  "question": "Should the proposal pass?",
  "options": ["yes", "no"],
  "voting_method": "yes_no",
  "start_time": 1700000000,
  "end_time": 1700086400,
  "status": "open",
  "created_at": 1699990000
}
Errors
CodeMeaning
5Poll not found

​
GET /polls//votes

Returns all vote directions for a closed poll (List 1). Available only after poll close. Response 
[
  {
    "ballot_id": "7c3a...",
    "poll_id": "referendum-2026-1",
    "choices": ["yes"],
    "timestamp": 1700040000,
    "height": 142
  }
]
ballot_id is H(BallotNonce) — a random value chosen by the voter. It does not encode the voter’s identity and cannot be linked to identity_hash without BallotNonce.

​
GET /polls//voters

Returns only the voter count for a poll (List 2 aggregate). Response 
{ "count": 1847 }
identity_hash values are never returned by this endpoint. This is a hard privacy constraint enforced at the handler level.