Topics

Every state names its subjects differently. Topics are a canonical taxonomy laid over those raw subject strings, so one query means the same thing in all 52 jurisdictions.

Two layers

Raw subjects are what each legislature publishes — thousands of state-specific strings, exposed as-is at /v1/subjects and on each bill at /v1/bills/{bill_id}/subjects.
Canonical topicsare Delilah's cross-state layer. Each topic maps to many raw subjects, so filtering by one topic slug reaches bills that no single subject string would have found.

Browse the taxonomy

/v1/topics returns every topic with a live bill count. Slugs are lowercase and hyphenated, for example healthcare.

bash

curl https://delilah-api.jsv21b.workers.dev/v1/topics \
  -H "X-API-Key: dk_live_…"

json

{
  "data": [
    {
      "slug": "<string>",
      "display_name": "<string>",
      "description": "<string>",
      "emoji": "<string>",
      "sort_order": "<int>",
      "bill_count": "<int>"
    }
  ]
}

Look inside a topic

/v1/topics/{slug} adds raw_subjects_mapped — how many state subject strings feed the topic — and sample_subjects, up to 25 of them ordered by bill count. It is the quickest way to check that a topic covers what you expect before you build on it.

bash

curl https://delilah-api.jsv21b.workers.dev/v1/topics/healthcare \
  -H "X-API-Key: dk_live_…"

Filter bills by topic

Pass the slug to /v1/bills?topic=. Combine it with state, session_id, status_id, or updated_since to narrow further.

bash

curl "https://delilah-api.jsv21b.workers.dev/v1/bills?topic=healthcare&state=FL&limit=50" \
  -H "X-API-Key: dk_live_…"

Three related filters exist on the same endpoint and are easy to confuse: topic takes a canonical slug, subject matches a raw subject name, and q is free text across title, description, and subject names.

The raw firehose

If you would rather build your own grouping, /v1/subjects rolls up the raw subject names with counts and accepts state, q, and limit. It is filtered to real legislative subjects — portal UI labels like “Bill Text” or “My Bills” are excluded.

bash

curl "https://delilah-api.jsv21b.workers.dev/v1/subjects?state=TX&q=water" \
  -H "X-API-Key: dk_live_…"

Missing a topic you need? Tell us what you are tracking — the taxonomy grows with customer demand, and adding a mapping is a server-side change with no re-integration on your end.