API REFERENCE

Civic Beacon API

Federal legislation data with AI-powered summaries, designed for advocacy organizations, newsrooms, and civic education programs. Stable, versioned, and production-ready. Use a free 30-day test key below — no credit card.

Quickstart Get a test key

Quickstart

Every request includes your API key in the X-API-Key header. Bills are returned as paginated JSON. AI summaries are generated on demand from the bill text.

One curl call to confirm your key works:

curl

curl -H "X-API-Key: cb_org_test_xxxxxxxxxxxxxxxx" \
  https://api.civicbeacon.app/api/v3/bills?limit=3

A successful response looks like:

json

{
  "object": "list",
  "items": [
    {
      "object": "bill",
      "id": 12345,
      "congress": 119,
      "bill_type": "hr",
      "bill_number": 1234,
      "title": "Healthcare Affordability Act",
      "introduced_date": "2026-04-15",
      "latest_action_date": "2026-04-22",
      "latest_action_text": "Reported by Committee on Energy and Commerce",
      "policy_areas": ["Health"],
      "sponsor": {
        "bioguide_id": "D000563",
        "full_name": "Sen. Dick Durbin",
        "party": "D",
        "state": "IL"
      }
    }
  ],
  "next_cursor": 12350,
  "has_more": true
}

Authentication

Every request must include an API key. Two ways to send it:

Header (preferred): X-API-Key: cb_org_xxxxxxxxxxxxxxxx
Query parameter (for embeds): ?api_key=cb_org_xxxxxxxxxxxxxxxx

Two key types exist. They differ only in expiration; both work against every endpoint.

Prefix	Type	Expires	Get one
`cb_org_test_*`	Test (sandbox)	30 days	Free signup below
`cb_org_*`	Live (production)	Never	Subscribe to a paid plan

Treat your API key like a password. Don't commit it to public repos. If you accidentally leak one, contact support to rotate it.

Rate limits

The default per-key rate limit is 200 requests per minute. Both test and live keys share this limit.

When you exceed the limit, you'll get a 429 Too Many Requests response. Back off and retry after a few seconds. If you need a higher limit for a legitimate use case (e.g., bulk historical research), reply to your onboarding email and we'll bump it for your account.

AI summary endpoints are subject to additional cost-based throttling on test keys (the underlying LLM tokens cost real money). If you're stress-testing, focus on cheap endpoints like list-bills.

Errors

Errors are returned with a 4xx or 5xx status code and a JSON body:

json

{
  "error": "this test API key has expired — request a new one or upgrade to a paid plan"
}

Status	Meaning
400	Bad request — malformed JSON or missing required field
401	Missing, invalid, or expired API key
403	Org deactivated, or feature not available on your plan
404	Resource doesn't exist
409	Conflict — usually duplicate creation (e.g. a topic that already exists)
429	Rate limit exceeded — back off and retry
500	Server error — retryable, please report if persistent

Pagination

List endpoints use cursor pagination. The response includes next_cursor and has_more:

json

{
  "object": "list",
  "items": [ /* up to 100 items */ ],
  "next_cursor": 12350,
  "has_more": true
}

Pass the cursor as ?after=12350 on the next request to get the next page. has_more: false means you've reached the end. Default page size is 20; max is 100 via ?limit=100.

Endpoints

GET /api/v3/bills

List bills

Returns paginated federal bills. Filter by topic, state, congress, or policy area. Most clients want this as their primary feed.

Parameters

`topic` string · query	Filter by tracked topic identifier (e.g. "healthcare"). See your org topics with /api/v3/org/topics.
`state` string · query	Filter to bills sponsored or cosponsored by legislators from this state (2-letter code, e.g. "IL").
`congress` int · query	Filter to a specific Congress number (e.g. 119). Defaults to current.
`limit` int · query	Page size, 1-100. Defaults to 20.
`after` int · query	Cursor for next page (use the next_cursor from the previous response).

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  "https://api.civicbeacon.app/api/v3/bills?topic=healthcare&limit=10"

Example response

json

{
  "object": "list",
  "items": [
    {
      "object": "bill",
      "id": 12345,
      "congress": 119,
      "bill_type": "hr",
      "bill_number": 1234,
      "title": "Healthcare Affordability Act",
      "introduced_date": "2026-04-15",
      "latest_action_date": "2026-04-22",
      "latest_action_text": "Reported by Committee on Energy and Commerce",
      "policy_areas": ["Health"],
      "sponsor": {"bioguide_id":"D000563","full_name":"Sen. Dick Durbin","party":"D","state":"IL"}
    }
  ],
  "next_cursor": 12350,
  "has_more": true
}

GET /api/v3/bills/{id}

Get bill

Single bill detail with full text URL, sponsors, cosponsors, votes, and committee actions.

Parameters

id

int · path

Bill ID from a list response.

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/bills/12345

Example response

json

{
  "object": "bill",
  "id": 12345,
  "congress": 119,
  "bill_type": "hr",
  "bill_number": 1234,
  "title": "Healthcare Affordability Act",
  "summary": "...",
  "text_url": "https://www.congress.gov/119/bills/hr1234/BILLS-119hr1234.xml",
  "introduced_date": "2026-04-15",
  "latest_action_text": "Reported by Committee on Energy and Commerce",
  "policy_areas": ["Health"],
  "sponsors": [...],
  "cosponsors": [...],
  "votes": [...],
  "committee_actions": [...]
}

GET /api/v3/bills/{id}/summary

AI bill summary

Generates (or returns cached) plain-English summary of the bill — the differentiator versus raw Congress.gov data. Cached for 24 hours per bill.

Parameters

id

int · path

Bill ID.

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/bills/12345/summary

Example response

json

{
  "object": "ai_summary",
  "bill_id": 12345,
  "summary": "This bill caps out-of-pocket prescription drug costs at $2,000/year for Medicare beneficiaries, and requires HHS to negotiate prices on the top 50 drugs by Medicare spend. It also extends ACA premium subsidies through 2028.",
  "key_points": [
    "Caps prescription costs at $2,000/year",
    "HHS price negotiation expanded to 50 drugs",
    "ACA subsidies extended through 2028"
  ],
  "generated_at": "2026-04-22T14:30:00Z",
  "cached": true
}

GET /api/v3/representatives

List representatives

Federal legislators with party, state, district, and committee memberships. Filter by state or chamber.

Parameters

`state` string · query	2-letter state code (e.g. "IL").
`chamber` string · query	"house" or "senate".
`limit` int · query	Page size, 1-100.

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  "https://api.civicbeacon.app/api/v3/representatives?state=IL&chamber=senate"

Example response

json

{
  "object": "list",
  "items": [
    {
      "object": "representative",
      "bioguide_id": "D000563",
      "full_name": "Dick Durbin",
      "party": "D",
      "state": "IL",
      "chamber": "senate",
      "district": null,
      "image_url": "https://unitedstates.github.io/images/congress/original/D000563.jpg"
    }
  ]
}

GET /api/v3/org

Get org profile

Returns your organization's plan, member count, and tracked topics.

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/org

Example response

json

{
  "object": "organization",
  "id": "0a1b2c3d-...",
  "name": "League of Women Voters Illinois",
  "plan": "pro",
  "member_count": 4,
  "max_members": 25,
  "topic_count": 6
}

GET /api/v3/org/members

List org members

Members linked to your org through the consumer mobile app. Use to see who's actively tracking legislation.

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/org/members

Example response

json

{
  "object": "list",
  "items": [
    {"object": "member", "user_id": "...", "joined_at": "2026-03-12T..."}
  ]
}

GET POST DELETE /api/v3/org/topics

Manage tracked topics

Topics filter the bills you and your members care about. Add the topics your org actively follows; the bills feed and member-engagement analytics will scope to them.

Example request

curl

# List
curl -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/org/topics

# Add (replaces list of keywords)
curl -X POST -H "X-API-Key: $CB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"voting rights","keywords":["voter id","ballot access","redistricting"]}' \
  https://api.civicbeacon.app/api/v3/org/topics

# Remove
curl -X DELETE -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/org/topics/voting-rights

Example response

json

{
  "object": "list",
  "items": [
    {"object":"topic","topic":"voting rights","keywords":["voter id","ballot access","redistricting"]}
  ]
}

GET /api/v3/org/usage

API usage stats

Daily breakdown of API calls by endpoint. Useful for capacity planning and confirming you're under the rate limit.

Parameters

since

ISO date · query

Start date (defaults to 30 days ago).

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  "https://api.civicbeacon.app/api/v3/org/usage?since=2026-04-01"

Example response

json

{
  "object": "list",
  "items": [
    {"endpoint":"/api/v3/bills","date":"2026-04-22","request_count":847},
    {"endpoint":"/api/v3/bills/{id}/summary","date":"2026-04-22","request_count":12}
  ]
}

GET /api/v3/org/analytics

Member engagement analytics

Aggregated stats on what bills and reps your members are tracking in the consumer mobile app. Useful for board reports and impact storytelling.

Example request

curl

curl -H "X-API-Key: $CB_KEY" \
  https://api.civicbeacon.app/api/v3/org/analytics

Example response

json

{
  "tracked_bills": 47,
  "tracked_representatives": 8,
  "actions_taken_30d": 113,
  "top_topics": ["healthcare","voting rights","climate"]
}

Try it — get a free 30-day test key

Enter your org name and email. We'll provision a sandbox API key, email it to you, and surface it on this page. No credit card. The key works against every endpoint, expires in 30 days, and can be upgraded to a live key anytime.

Need help?

This page is the canonical reference, but if something's missing or unclear, just ask:

Email: [email protected] — replies within 24 hours on weekdays
Onboarding call: Schedule a 30-minute walkthrough
Status page: coming soon