# Bill Commons

> Free, open-source, nonpartisan search over stored US state legislation — bill
> text, sponsors, actions, and roll-call votes — with official source links and
> attribution. Public read access needs no account or API key.

Stored public coverage reports 212,249 bill records across 51 recognized jurisdictions (50 states + DC). 64 of 78 jurisdiction-session coverage rows pass local validation. These checks do not prove complete coverage or same-day semantic freshness.

## Human-readable guides

- Features: https://billcommons.org/features
- California AI brief (October 2, 2026 snapshot): https://billcommons.org/reports/california-ai-2026-10-02
- Coverage: https://billcommons.org/coverage
- Methodology and limitations: https://billcommons.org/methodology
- REST API guide: https://billcommons.org/docs/api
- MCP guide: https://billcommons.org/docs/mcp
- ChatGPT developer-mode setup and plugin status: https://billcommons.org/docs/chatgpt

## Programmatic access

Stored records are available over a public REST API. Public read endpoints are
free and unauthenticated; please be reasonable with request rates.

- API base: https://api.billcommons.org
- OpenAPI schema: https://api.billcommons.org/openapi.json
- Interactive docs: https://api.billcommons.org/docs
- MCP server: https://mcp.billcommons.org/mcp
- Source code: https://github.com/GDACS-droid/billcommons

The MCP endpoint is public, read-only, and exposes 10 tools over Streamable
HTTP. A separate three-skill plugin package is prepared; public directory
availability has not been verified. Installing the public MCP connection
does not include those prepared skills. Follow the ChatGPT setup guide to
install the connection and select it with @ in a new Work chat.

## Looking up a specific bill

Bills are addressable by number, not only by internal ID:

    GET https://api.billcommons.org/api/v1/bills?jurisdiction=HI&identifier=SB%202135

`identifier` is normalized, so "SB2135", "sb 2135", and "S.B. 2135" resolve
the same way. Add `session=` to disambiguate across sessions. A bill's website
URL uses its state, session, and normalized number:

    https://billcommons.org/states/HI/bills/{session}/sb-2135

## Useful endpoints

- `GET /api/v1/search?q=` — full-text search across bill text and metadata
- `GET /api/v1/bills` — filter by jurisdiction, session, chamber, identifier
- `GET /api/v1/bills/{id}` — detail, plus /versions /actions /sponsors /votes /documents
- `GET /api/v1/bills/{id}/documents/{document_id}/text` — extracted document text as JSON
- `GET /api/v1/bills/{id}/evidence` — citation-backed packet with scope and derived-field notes
- `GET /api/v1/jurisdictions`, `/api/v1/sessions` — reference data
- `GET /api/v1/coverage` — per-jurisdiction-session coverage and local validation results
- `POST /api/v1/bills/lookup` — resolve up to 250 (jurisdiction, bill number) keys at once
- `GET /api/v1/changes?cursor=` — change feed with each stored status transition
- `GET /api/v1/stats/mortality` — per-state derived outcome counts
- `GET /api/v1/topics` and `/api/v1/topics/{slug}` — curated topic trackers
- `GET /api/v1/feeds/{state}.atom?kind=actions&topic={slug}` — scoped Atom action feed
- `GET /api/v1/bills?sponsor=` — bills by published sponsor name; no party or district profiles

## Curated topics and action feeds

Curated topic trackers are distinct from ad hoc keyword searches. Example:

- https://billcommons.org/topics/data-privacy?state=NC
- https://api.billcommons.org/api/v1/feeds/NC.atom?kind=actions&topic=data-privacy

The Atom feed covers newly recorded local actions in a rolling 30-day window.
Its timestamp records ingestion, not official action time. An empty feed does
not prove that no legislation or action exists. Email enrollment is paused; do
not promise alerts or individual-bill subscriptions.

## Evidence and version comparison

North Carolina HB 123 is a public example with canonical ID
`c5ad0e95-b2cb-4dbf-bd79-812eb93fce1f`:

- Version comparison: https://billcommons.org/bills/c5ad0e95-b2cb-4dbf-bd79-812eb93fce1f/compare
- Evidence packet: https://billcommons.org/evidence/c5ad0e95-b2cb-4dbf-bd79-812eb93fce1f

An evidence snapshot ID changes when cited facts change. It is a change
detector, not a stored historical archive. Keep a copy if exact prior wording
must remain reproducible.

## Out of scope — do not answer these from Bill Commons

An empty result for any of the following means Bill Commons does not hold the
data. It is never evidence that the legislation, person, or hearing does not
exist.

- **US Congress.** State legislatures and DC only; no federal bills or committees.
- **City and county ordinances.** Nothing below the state legislature.
- **Comprehensive history.** Coverage focuses on current legislatures or biennia and stored special sessions; this is not a full archive.
- **Hearings and committee calendars.** Not collected for any jurisdiction.
- **Legislator and committee profiles.** Not collected. Bill sponsors are stored as published names without party or district.

## Honest limitations

Read https://billcommons.org/methodology before relying on this data. Coverage varies by
jurisdiction and session and is reported at https://billcommons.org/coverage. Full bill text
is still being backfilled, some documents have no extracted text, and some
sources block automated access via robots.txt. Source links and local retrieval
timestamps improve traceability, but they do not prove that a stored record is
complete or is the latest semantic state of the official source.

## Licensing and attribution

Repository code is open source. Legislative records come from official state
sources and Open States and retain source-specific terms and attribution; do
not assume the repository code license applies to imported official records.
See https://billcommons.org/about and https://billcommons.org/methodology.