Developer reference

Aclamos REST API

Build into Aclamos. Read shows, nominations, winners, judges, sponsor payouts, and Ballotis tallies; get live updates via webhooks. OpenAPI 3.1, JSON, bearer-token auth.

openapi.json →Quickstart

5-minute quickstart

1. Get a key

From your producer dashboard at /[org]/api-keys. Pick scopes; rotate any time.

2. Smoke-test

GET /api/v1/me works for any authenticated key — confirms the token is valid + lists your scopes.

3. Read your data

Hit any endpoint with the header Authorization: Bearer lmnry_live_…

curl

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

# List your shows
curl https://aclamos.app/api/v1/shows \
  -H "Authorization: Bearer lmnry_live_YOURKEY"

# Paginate nominations for one show
curl "https://aclamos.app/api/v1/nominations?showId=cl_abc&limit=50" \
  -H "Authorization: Bearer lmnry_live_YOURKEY"

Authentication

API keys are issued per-org with explicit scopes. Send the key as a Bearer token on every request. Keys are stored as SHA-256 hashes server-side; we cannot recover a lost key — issue a new one and rotate.

Token formats

Three families share the same auth + database table.

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.

Scopes

Token carries the minimum set you grant.

shows:read — shows + categories + judges

nominations:read — nominations + their fee snapshots

polls:read — Ballotis polls + tallied results

vote:tally:read — show-voting-period tallies

winners:read — winners + badge URLs

finance:read — show finance summary + sponsor payouts

Conventions

Success envelope

List endpoints add a meta block with the cursor.

{
  "data": [ /* one or many records */ ],
  "meta": { "count": 50, "nextCursor": "clx1y2z3..." }
}

Error envelope

Always: error.code, error.message, optional error.details.

{
  "error": {
    "code": "forbidden",
    "message": "Token is missing required scope: nominations:read",
    "details": { "requiredScopes": ["nominations:read"] }
  }
}

Pagination

Cursor + limit. Default 50, max 100.

# First page
GET /api/v1/nominations?limit=50

# Next page — pass the cursor from the previous response's meta.nextCursor
GET /api/v1/nominations?limit=50&cursor=clx1y2z3...

Rate limits

Per API key, sliding window.

· 60 req/min read endpoints (Starter, Growth)

· 240 req/min read endpoints (Studio, Enterprise)

· Write endpoints share a separate, lower bucket

429 responses include Retry-After.

Endpoint reference

Full machine-readable spec at /api/v1/openapi.json.

Method	Path	Scope	Summary
GET	/api/v1/me	`(any)`	Whoami: org + key + scopes.
GET	/api/v1/shows	`shows:read`	List non-archived shows.
GET	/api/v1/categories?showId=…	`shows:read`	Categories for a show.
GET	/api/v1/judges	`shows:read`	Judges in the org.
GET	/api/v1/nominations	`nominations:read`	List nominations (filterable).
GET	/api/v1/winners	`winners:read`	Recent winners + badge URLs.
GET	/api/v1/polls	`polls:read`	Ballotis polls in the org.
GET	/api/v1/polls/{id}/results	`polls:read`	Tallied per-option results.
GET	/api/v1/voting-period/{id}/tally	`vote:tally:read`	Tally a show voting period.
GET	/api/v1/finance/summary?showId=…	`finance:read`	Revenue + tier breakdown.
GET	/api/v1/sponsor-payouts	`finance:read`	Sponsor revenue-share payouts.

Webhooks

Configure outbound webhooks at /[org]/webhooks. Each delivery is signed with HMAC-SHA256 in a Stripe-style Aclamos-Signature header.

Events

nomination.submitted

payment.succeeded

judge.invited

review.submitted

winner.announced

Signature verification

Verify the body matches the timestamped HMAC.

# Header: Aclamos-Signature: t=1717029300,v1=abcd1234...
# Verify in pseudo-code:
expected = hmac_sha256(secret, t + "." + raw_body)
constant_time_eq(expected, v1)

Need an SDK?

Generate one in five minutes.

The OpenAPI 3.1 spec is the source of truth. Pipe it through Speakeasy, openapi-generator, or your favorite codegen.

Get the spec