Authentication

Every /v1/* data endpoint requires an API key sent in the X-API-Key header.

The X-API-Key header

Delilah uses an API-key header, not an Authorization: Bearer token. Send it on every request.

http

X-API-Key: dk_live_<token>

bash

curl "https://delilah-api.jsv21b.workers.dev/v1/legislators?state=FL&chamber=Senate" \
  -H "X-API-Key: dk_live_…"

Keys are hashed at rest, so a lost key cannot be recovered — it has to be re-issued. Never ship a key in client-side code; keep it on your server. Browser calls are possible (the API sends Access-Control-Allow-Origin: * and allows the X-API-Key header) but any key you put in a browser is a public key.

Getting a key

Keys are provisioned by Delilah after a short review — there is no self-serve signup. Request a key with your organization and intended use and we will respond within one business day. Each key carries a tier, a monthly request cap, and a burst limit; see Rate limits.

Public endpoints

These three need no key, so you can measure the data before you integrate:

GET /v1/health — liveness.
GET /v1/status — per-state freshness snapshot, cached 60s.
GET /v1/coverage — per-state depth snapshot with reference-provider ratios.

The machine-readable spec at GET /openapi.json and the reference page at GET /docs are public too.

Failed authentication

All three auth failures return 401 with the standard error envelope. The code tells you which one it is.

json

{
  "error": {
    "code": "unauthorized",
    "message": "Missing X-API-Key header.",
    "request_id": "573ffd34-54e2-4cc5-8542-a15b71c7e9e5",
    "docs": "https://delilah-api.jsv21b.workers.dev/docs"
  }
}

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "232c8363-e49d-446f-8fd4-84d880868132",
    "docs": "https://delilah-api.jsv21b.workers.dev/docs"
  }
}

Code	HTTP	Meaning
`unauthorized`	401	No `X-API-Key` header was sent
`invalid_api_key`	401	The key does not match any issued key
`revoked_api_key`	401	The key was issued but has since been revoked

Usage and rotation

GET /v1/_meta/usagereports the calling key's tier, monthly cap, requests used and remaining, and the current billing period. To rotate a key, raise a limit, or change tiers, reply to your provisioning email or submit a new request — we can overlap the old and new keys during your cutover.

For the full list of error codes, see Errors.