The Voting API is the primary integration surface for Ekklesia. The frontend is a thin client around this API — anything the UI can do, you can do programmatically.

API Versions

The Voting API has two coexisting versions:

v1 — Live (Hydra-backed)

The active surface for all new ballots. Votes are processed through the Hydra broker pipeline and settled on-chain. v1 also publishes the audit artifacts (per-proposal canonical content, archive bundle, certification state) and the cross-source unified ballot listing.

• Unified ballot listing across all sources (Hydra + archived legacy)
• Vote broker — draft / sign / submit pipeline for Hydra-powered votes, with multisig support and rehydration
• Results — separate, poll-friendly endpoints for provisional + final tallies
• Audit endpoints — content blobs, downloadable archive bundle, and authority certification state
• Public integrator surface — API-key gated read-only access

Operational endpoints that talk directly to the Hydra head — ballot prepare / start / settlement, ingestion, voting-power uploads, certification ingest — are administrator-only and not part of the published API surface.

All endpoints are prefixed with /api/v1/. View the full interactive specification or download the OpenAPI YAML.

v0 — Archival + Live Read

The legacy API surface. Writes to ballot, proposal, vote, voter, transaction, and dashboard resources return HTTP 410 Gone with a pointer to the v1 equivalent. Read endpoints remain available for archived ballots, and the Session, Comments, and FAQs endpoints continue to function on v0 — those handle authentication and pre-vote feedback for both versions.

All endpoints are prefixed with /api/v0/. View the full v0 interactive specification or download the v0 OpenAPI YAML.

Authentication

The published surface uses two authentication methods:

Voter authentication uses CIP-8 message signing: request a nonce, sign with your wallet or keys, receive a JWT session cookie. Standard and multisig (script-address) voters share a single set of session endpoints — include scriptAddress in the request body for multisig. See the Wallet Integration guide for the full handshake.

API keys are scoped (read:ballots, read:results, etc.) and rate-limited per key. Contact the voting authority for a key.

v1 Endpoints

Health & Config

/config is public and unauthenticated — frontends and third-party integrators read it to render explorer / IPFS links without hardcoding a network.

Unified Ballots

Each ballot row includes a source field ("legacy" or "hydra") and a hydra sub-object with head status (null for legacy ballots). Responses use status-aware caching: closed = 3600 s, live = 120 s, upcoming = 30 s. The list response is cached for 60 s.

Proposals

Sort and filter keys must be declared on Ballot.facets[]. Multi-value enum filters take comma-separated values; OR within a facet, AND across facets. Facets are frozen once a ballot goes live, so the filter UI can safely cache the facet list for the ballot’s lifetime.

Results

Results are separated from ballot detail for efficient polling.

Result rows carry source: "provisional" | "final" and the Hydra settlement artifacts (hydraResultsCid, hydraResultsHash, hydraEvidenceMerkleRoot, hydraTotalVoters, hydraExcludedVoters) once the ballot has been finalized.

/ballots/:id/certified distinguishes certified-by-authority results from provisional Hydra-final tallies. When a CertifiedSnapshot is active, results are flagged “Certified at version N by <authority>”; otherwise they’re labelled “Provisional”.

Audit Artifacts

Both endpoints are public and unauthenticated by design — long-term auditability requires no gate. The chain of custody runs:

on-chain (601) datum → ekklesia.merkleRoot
  → IPFS-pinned ballot JSON (covers BallotQuestion.contentHash[n])
    → per-proposal content blob (questions/:qid/content)

The /archive endpoint returns one JSON file with a per-file hash manifest (blake2b_256 + sha256) and a README containing the verification recipe. It’s served with Content-Disposition: attachment so browsers download instead of preview. See the Technical Auditor Guide for the full verification flow.

Vote Broker (Live Ballots)

The vote submission flow is a draft → sign → submit pipeline. Drafts are idempotent on (voter, ballot) — re-clicking /draft with matching selections returns the existing package; with different selections (and no collected signatures) it updates in place.

Step 1 — Draft. Reserve / resume a nonce and receive the canonical signing payload.

POST /api/v1/votes/:ballotId/draft
Body: { votes: [...], responderRole?, nativeScript?, calidusDeclaration? }

Returns: { status, package: { id, status, nonce }, signingPayload, signingPayloadHex, merkleRoot, signedPayloadJson, prelimVoteHash, multisig }.

Step 2 — Sign. The voter signs the merkleRoot (64-char hex string) using CIP-8 message signing to produce a COSE witness. Sign the hex characters verbatim — Hydra’s verifier compares the COSE payload ASCII against this exact string.

Step 3 — Submit. Send the witness to the broker.

POST /api/v1/votes/:ballotId/signature
Body: { packageId, witness: { coseSign1Hex, coseKeyHex, key, signature } }

The broker validates, aggregates (for multisig), and submits to Hydra when the signature threshold is met.

Public Integrator Surface

Read-only API for third-party tools. Requires an API key.

Authenticate with Authorization: Bearer <key> or x-api-key: <key>. Keys are scoped and rate-limited per key.

Operational Endpoints (Not Public)

Endpoints that talk directly to the Hydra head — ballot prepare / start, the stepped settlement sequence, head and queue observability, inspection helpers — together with ballot ingestion, voting-power snapshot uploads, and authority certification ingest are operated by voting administrators. They are not part of the published API surface and are intentionally omitted from this documentation. Instance operators can integrate against them out-of-band; if you are running a voting authority and need access, contact the instance administrator.

v0 Endpoints (Archival + Live Read)

The full v0 surface — including dashboard, transactions, and proposals lookup — lives in the v0 specification.

Health Probes

The voting backend exposes liveness probes at the server root, not under /api/vN. Mounted at: /health, /health/health, /health/db. The v1 surface also exposes /api/v1/health for v1-specific liveness.