> ## Documentation Index
> Fetch the complete documentation index at: https://docs.policymate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bills

> Search bills, filter them, and read their milestones and texts.

## Retrieving Bills

To retrieve a list of bills, send a `GET` request to the `/bills` endpoint. For example, the following request retrieves Texas bills that mention data centers, latest milestone first:

```http theme={null}
GET /api/v0/bills?jurisdiction=US-TX&q=%22data%20center%22&sort=-last_milestone_date
```

To retrieve a single bill, send a `GET` request to `/bills/{id}`. The response contains the bill along with its sponsors and latest milestone.

## Filtering Bills

The `/bills` endpoint accepts the following query parameters. Any of them may be combined:

| Parameter | Example | Description |
| - | - | - |
| `jurisdiction` | `US-TX` | Only bills from this jurisdiction. May be repeated. |
| `q` | `data center` | Full-text search over the number, title, description, and text |
| `status` | `in_procedure` | Only bills with this status |
| `category` | a category `id` | Only bills in this category or its children |
| `chamber` | `tx-house` | Only bills from this chamber |
| `sponsor` | a person `id` | Only bills this person sponsored |
| `introduced_after`, `introduced_before` | `2026-01-01` | Only bills introduced within this range |
| `updated_since` | `2026-11-04T00:00:00Z` | Only bills that changed since this time |
| `topic` | a topic `id` | Only bills recommended for this topic |
| `sort` | `-last_milestone_date` | Also `introduced_date`, or `relevance` when searching with `q`. Prefix with `-` for descending order. |

## The Bill Object

A bill looks like the following. The values below are illustrative:

```json theme={null}
{
  "id": "9b3e2c1a-4f5d-4b8e-a1c2-7d6e5f4a3b21",
  "type": "bill",
  "jurisdiction": { "id": "US-TX", "name": "Texas" },
  "number": "HB 1234",
  "title": "Relating to the water and energy use of large data centers.",
  "description": "Requires data centers above 75 MW to report annual water and electricity consumption to the Public Utility Commission.",
  "chamber": { "id": "tx-house", "name": "Texas House of Representatives" },
  "procedure_type": "bill",
  "status": "in_procedure",
  "introduced_date": "2027-01-14",
  "last_milestone": {
    "date": "2027-02-03",
    "type": "committee_action",
    "title": "Referred to State Affairs"
  },
  "sponsors": [
    { "person_id": "5c1d...", "name": "Jane Doe", "party": "Democratic Party" },
    { "person_id": "a7e2...", "name": "John Roe", "party": "Republican Party" }
  ],
  "categories": [ { "id": "0b6f2d4e-...", "label": "Energy policy" } ],
  "summary": { "text": "The bill would require ...", "source": "ai" },
  "links": {
    "official": "https://capitol.texas.gov/BillLookup/History.aspx?LegSess=90R&Bill=HB1234",
    "app": "https://app.policymate.io/entity/9b3e2c1a-..."
  },
  "mentions_count": 3,
  "created_at": "2027-01-15T06:12:40Z",
  "updated_at": "2027-02-04T06:10:02Z"
}
```

The `status` attribute describes the bill's legal state. It is deliberately coarse, so that it means the same thing in every legislature, and contains one of the following values: `draft`, `in_procedure`, `adopted`, `in_force`, `withdrawn`, `rejected`, `repealed`, or `expired`.

The `summary.source` attribute tells you who wrote the summary: `official` when the legislature publishes one, `editor` when our team wrote it, and `ai` when PolicyMate generated it from the bill's text.

## Milestones

A bill's history is made of milestones: its introduction, committee actions, readings, votes, and final outcome. You may retrieve a bill's milestones, oldest first, using the `GET /bills/{id}/milestones` endpoint:

```json theme={null}
{
  "date": "2027-04-22",
  "type": "chamber_vote",
  "title": "Passed the House on third reading",
  "source_url": "https://capitol.texas.gov/...",
  "document_url": "https://capitol.texas.gov/.../HB01234H.pdf",
  "vote": { "for": 98, "against": 47, "abstained": 0, "absent": 2, "not_voting": 3 }
}
```

A milestone's `type` is one of `proposed`, `committee_action`, `reading`, `chamber_vote`, `adopted`, `signed_into_law`, `entered_into_force`, `rejected`, `withdrawn`, `expired`, `repealed`, `document_published`, or `other`. When the source publishes vote counts, the milestone also includes a `vote` object.

## Bill Texts

The `GET /bills/{id}/texts` endpoint returns each version of a bill's text. Every version includes a link to the original file and, when available, a link to its plain text:

```json theme={null}
{
  "id": "71a2...",
  "name": "Introduced version",
  "mime_type": "application/pdf",
  "url": "https://capitol.texas.gov/.../HB01234I.pdf",
  "text_url": "https://app.policymate.io/api/v0/bills/9b3e2c1a-.../texts/71a2.../text",
  "text_method": "ocr"
}
```

The `text_method` attribute describes how the plain text was obtained: `source` when the legislature publishes the text itself, `extracted` when we read it from the file, or `ocr` when the file is a scan.

> [!WARNING]
>
> Plain text extracted from files, and especially text produced by OCR, may differ from the published wording. You should always treat the original file as the authoritative text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.