REST API: read your data, automate the boring parts

What's exposed

The public REST API at /api/v1/* covers read access across the most-requested surfaces:

/me — whoami; verifies your key + lists scopes
/shows — shows in your org
/categories?showId=… — categories for a show
/nominations — nominations (filterable by show / category / status)
/judges — judges in your org
/winners — recent winners + badge URLs
/polls — Ballotis polls
/polls/{id}/results — tallied per-option results
/voting-period/{id}/tally — show-bound voting period tallies
/finance/summary — revenue + tier breakdown
/sponsor-payouts — sponsor revenue-share payouts

Full machine-readable spec at /api/v1/openapi.json. Public dev portal at /developers.

Auth

API keys are issued from the producer dashboard at /[org]/api-keys. Pick scopes when you create the key — keys carry the minimum set you grant. Send as a Bearer token:

Authorization: Bearer lmnry_live_YOURKEY

Keys are stored as SHA-256 hashes; we can't recover a lost key, only revoke + reissue.

Token formats

lmnry_live_… — production server-to-server
lmnry_test_… — sandbox / dev environments
lmnry_mobile_… — issued by the mobile sign-in flow; bound to a single device

All three share the same auth path; only the scope set differs by default.

Smoke test

curl https://aclamos.app/api/v1/me \
  -H "Authorization: Bearer lmnry_live_YOURKEY"

Returns your org, your key info, and the scopes the key carries. If this 401s, the token is wrong; if it 200s, you're set.

Conventions

Success envelope:

{ "data": [ ... ], "meta": { "count": 50, "nextCursor": "clx1..." } }

Error envelope:

{ "error": { "code": "forbidden", "message": "...", "details": { ... } } }

Pagination: cursor + limit (default 50, max 100). Pass back the previous response's meta.nextCursor to fetch the next page.

Rate limits: 60 req/min on Starter/Growth, 240 req/min on Studio+. 429 includes Retry-After.

Webhooks (real-time push)

Configure outbound webhooks at /[org]/webhooks. Events: nomination.submitted, payment.succeeded, judge.invited, review.submitted, winner.announced.

Each delivery is HMAC-SHA256 signed in the Aclamos-Signature header (Stripe-style t=…,v1=… format). Verify in pseudo-code:

expected = hmac_sha256(secret, t + "." + raw_body)
constant_time_eq(expected, v1)

Generating an SDK

The OpenAPI 3.1 spec is the source of truth. Run it through any codegen — Speakeasy, openapi-generator, oas-cli, or your editor's plugin — and you'll get a typed client. We don't ship official SDKs yet (Phase 2).

What's not exposed

Write endpoints are deliberately scoped narrow in v1 — most state changes happen through the producer dashboard or webhooks-back-to-Aclamos. If you need to programmatically create nominations, invite judges, or open polls, contact developers@aclamos.app with your use case; we're prioritizing v1 writes by demand.

Versioning

v1 is stable. Breaking changes will land at /api/v2; v1 stays online for at least 12 months after a v2 release.