API Reference

The Docket Room REST API gives programmatic access to bills, legislators, and search. It is available on the Team and Enterprise plans. Generate and manage keys in Settings → API.

Base URL

https://docketroom.ai/api/v1

Authentication

Authenticate every request with a Bearer token in the Authorization header. Keys are prefixed cvts_ and are shown only once at creation — store them securely.

Authorization: Bearer cvts_your_key_here

Each key is granted scopes (bills, legislators, search, regulations); a request to an endpoint outside the key's scopes returns 403. Hearings ride under the bills scope.

Rate limits

Requests are limited per key on a rolling one-hour window (default 1,000/hour). Over the limit returns 429 with a Retry-After header. Every response carries:

X-RateLimit-Limit — your hourly cap
X-RateLimit-Remaining — requests left in the window
X-RateLimit-Reset — ISO timestamp when the window resets

Pagination

List endpoints accept page and limit and return a pagination object with page, limit, total, and has_more.

Endpoints

GET/v1/billsscope: bills

List bills, most recently acted first. Includes plain-language summaries.

Parameters

`state`	string	Two-letter state code (e.g. CA), or US for federal.
`status`	string	Filter by canonical status (e.g. introduced, in_committee).
`tag`	string	Filter by issue tag (e.g. Healthcare).
`sponsor`	string	Sponsor name substring (e.g. Wiener).
`committee`	string	Committee name substring (e.g. Judiciary) — bills currently before that committee.
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 25).

Example request

curl "https://docketroom.ai/api/v1/bills?state=CA&limit=2" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [
    {
      "id": "…",
      "number": "AB-1",
      "state": "CA",
      "title": "…",
      "status": "in_committee",
      "last_action_at": "2026-06-25T…",
      "summaries": [{ "id": "…", "level": "short", "content": "…" }]
    }
  ],
  "pagination": { "page": 1, "limit": 2, "total": 1234, "has_more": true }
}

GET/v1/bills/{id}scope: bills

Retrieve a single bill with summaries, stage predictions, related hearings, and committee history (current_committee + committees[]).

Parameters

idrequired string The bill's Docket Room id (path parameter).

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": {
    "id": "…",
    "number": "HR-1",
    "summaries": [ … ],
    "predictions": [{ "stage": "passed_chamber", "probability": 0.42, "explanation": "…" }],
    "hearings": [{ "id": "…", "title": "…", "hearing_date": "…", "relationship": "primary" }]
  }
}

GET/v1/changesscope: bills

Monitoring feed: field-level bill changes (new actions, status changes, new bills, sponsor changes) detected by the nightly ingest, newest first.

Parameters

`since`	string	ISO date, e.g. 2026-07-01. Default: 7 days back. Max window: 90 days.
`state`	string	Two-letter state code (US for federal).
`change_type`	string	action_update, status_change, new_bill, cosponsor_change, sponsor_change, or amendment (substantive text change between versions).
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 25).

Example request

curl "https://docketroom.ai/api/v1/changes?state=CA&change_type=status_change&since=2026-07-01" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [
    {
      "bill_id": "…",
      "bill_number": "AB-1",
      "state": "CA",
      "bill_title": "…",
      "change_type": "status_change",
      "field": "status",
      "old_value": "passed_chamber",
      "new_value": "signed",
      "detected_at": "2026-07-12T…",
      "url": "https://docketroom.ai/bills/…"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 312, "has_more": true }
}

GET/v1/bills/{id}/changesscope: bills

One bill's detected change history, newest first (same rows as /v1/changes).

Parameters

`id`required	string	The bill's Docket Room id (path parameter).
`since`	string	ISO date. Default: 7 days back. Max window: 90 days.
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 25).

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/changes?since=2026-06-15" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [ { "change_type": "action_update", "new_value": "…", "detected_at": "…" } ],
  "pagination": { "page": 1, "limit": 25, "total": 8, "has_more": false }
}

GET/v1/legislatorsscope: legislators

List in-office legislators.

Parameters

`state`	string	Two-letter state code.
`chamber`	string	Chamber (e.g. upper, lower, house, senate).
`party`	string	Party affiliation — full name or short code (Democratic or D, Republican or R).
`q`	string	Name search (matches full name).
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 50).

Example request

curl "https://docketroom.ai/api/v1/legislators?state=NY&party=D" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [ { "id": "…", "full_name": "…", "state": "NY", "chamber": "…", "party": "Democratic" } ],
  "pagination": { "page": 1, "limit": 50, "total": 213, "has_more": true }
}

GET/v1/bills/{id}/versionsscope: bills

Stored text versions in chronological order (1 = introduced). Version tracking covers federal bills nightly plus archived state versions.

Parameters

idrequired string The bill's Docket Room id (path parameter).

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/versions" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [
    { "version_num": 1, "version_name": "Introduced in Senate", "version_date": "…", "has_text": true, "chars": 10819, "source_url": "https://www.congress.gov/…" },
    { "version_num": 3, "version_name": "Engrossed in Senate", "version_date": "…", "has_text": true, "chars": 18777, "source_url": "…" }
  ]
}

GET/v1/bills/{id}/versions/comparescope: bills

Structured amendment analysis between two versions (default: the latest pair): added/removed/modified changes classified substantive vs technical, categorized (penalty, scope, enforcement, effective_date, coverage, definitions, appropriations), with verbatim quotes re-verified against the correct version's text. First call generates (~1 min); cached afterward.

Parameters

`id`required	string	The bill's Docket Room id (path parameter).
`from`	integer	Older version_num (default: the one before 'to').
`to`	integer	Newer version_num (default: latest).
`refresh`	string	true → regenerate even if cached.

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/versions/compare" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": {
    "from": { "num": 2, "name": "Reported to Senate" }, "to": { "num": 3, "name": "Engrossed in Senate" },
    "mechanical": { "added_spans": 2, "removed_spans": 2, "truncated": false, "identical": false },
    "quote_verification": { "verified": 4, "unverified": 0 },
    "analysis": {
      "summary": "…", "materially_substantive": true,
      "changes": [ { "side": "removed", "category": "substantive", "kind": "scope", "description": "…", "significance": "…", "quote": "…", "verified": true } ]
    }
  }
}

GET/v1/bills/{id}/analysisscope: bills

Structured AI analysis: covered entities, requirements/prohibitions/exemptions/penalties, effective dates, enforcement agencies, ambiguous language. Every item carries a verbatim quote re-verified against the bill text (verified=true → explicit bill language; false → model interpretation). First call generates (~1 min); cached afterward.

Parameters

`id`required	string	The bill's Docket Room id (path parameter).
`refresh`	string	true → regenerate even if cached.

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/analysis" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": {
    "bill_id": "…",
    "model_version": "…",
    "text_coverage": { "has_text": true, "total_chars": 12189, "analyzed_chars": 12189, "truncated": false },
    "quote_verification": { "verified": 30, "unverified": 0 },
    "analysis": {
      "plain_summary": "…",
      "covered_entities": [ { "entity": "…", "quote": "…", "section": "22626(a)", "verified": true } ],
      "provisions": [ { "kind": "prohibition", "description": "…", "quote": "…", "section": "…", "verified": true } ],
      "effective_dates": [ … ], "agencies": [ … ], "ambiguities": [ … ],
      "confidence": "high", "notes": null
    },
    "disclaimer": "AI-generated analysis, not legal advice. …"
  }
}

GET/v1/bills/{id}/textscope: bills

The bill's original legislative text as ingested (not a summary), chunked via offset/max_chars for large bills.

Parameters

`id`required	string	The bill's Docket Room id (path parameter).
`offset`	integer	Character offset for chunking (default 0).
`max_chars`	integer	Chunk size, 1,000–500,000 (default 100,000).

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/text?max_chars=5000" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": {
    "bill_id": "…",
    "has_text": true,
    "text": "SECTION 1. …",
    "offset": 0,
    "total_chars": 48210,
    "truncated": true,
    "source_text_url": "https://…"
  }
}

GET/v1/bills/{id}/cosponsorsscope: bills

The full cosponsor list (bill detail carries only the count). legislator_id links into /v1/legislators when resolved.

Parameters

`id`required	string	The bill's Docket Room id (path parameter).
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 50).

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/cosponsors" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [ { "name": "…", "party": "D", "state": "CA", "legislator_id": "…", "cosponsor_date": "…" } ],
  "pagination": { "page": 1, "limit": 50, "total": 42, "has_more": false }
}

GET/v1/bills/{id}/relatedscope: bills

Embedding-similar bills — companions, copied/model legislation, and same-topic bills in other states, most similar first.

Parameters

`id`required	string	The bill's Docket Room id (path parameter).
`exclude_same_state`	string	true → only other jurisdictions (multistate survey).
`limit`	integer	Results, 1–20 (default 10).

Example request

curl "https://docketroom.ai/api/v1/bills/BILL_ID/related?exclude_same_state=true" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [ { "bill_id": "…", "similarity": 0.87, "number": "SB 12", "state": "WA", "title": "…", "url": "…" } ]
}

GET/v1/hearingsscope: bills

Hearings calendar across all 50 states + Congress. Defaults to upcoming (soonest first); pass from/to for a historical window.

Parameters

`state`	string	Two-letter state code (US for Congress).
`bill_id`	string	Only hearings linked to this bill.
`from`	string	ISO date lower bound (default: today).
`to`	string	ISO date upper bound.
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 25).

Example request

curl "https://docketroom.ai/api/v1/hearings?state=OH&limit=3" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [
    {
      "id": "…",
      "state": "OH",
      "committee": "Senate Finance",
      "title": "…",
      "hearing_date": "2026-07-16T…",
      "status": "scheduled",
      "url": "https://docketroom.ai/hearings/…"
    }
  ],
  "pagination": { "page": 1, "limit": 3, "total": 12, "has_more": true }
}

GET/v1/regulationsscope: regulations

Federal rulemaking (Federal Register): keyword search, agency filter, and open_for_comment=true for rules still accepting public comments (most urgent deadline first).

Parameters

`q`	string	Keyword phrase (full-text search).
`agency`	string	Agency name substring, e.g. 'Environmental Protection'.
`tag`	string	Filter by issue tag.
`open_for_comment`	string	true → only rules whose comment window is open.
`page`	integer	Page number (default 1).
`limit`	integer	Results per page, 1–100 (default 25).

Example request

curl "https://docketroom.ai/api/v1/regulations?q=artificial%20intelligence&open_for_comment=true" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [
    {
      "id": "fedreg-2026-…",
      "document_number": "2026-…",
      "title": "…",
      "agency": "…",
      "comments_close_on": "2026-08-01",
      "comment_open": true,
      "url": "https://docketroom.ai/regulations/…"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 7, "has_more": false }
}

GET/v1/regulations/{id}scope: regulations

One regulation with full detail (abstract, agencies, comment deadline, Federal Register link) and its related bills.

Parameters

idrequired string Docket Room id (fedreg-…) or a bare Federal Register document number.

Example request

curl "https://docketroom.ai/api/v1/regulations/fedreg-2026-01234" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": {
    "id": "fedreg-2026-01234",
    "title": "…",
    "abstract": "…",
    "agencies": ["…"],
    "comments_close_on": "2026-08-01",
    "source_url": "https://www.federalregister.gov/…",
    "related_bills": [ { "id": "…", "number": "HB 1", "state": "…", "url": "…" } ]
  }
}

GET/v1/searchscope: search

Search bills — keyword (default) or semantic (meaning-based).

Parameters

`q`required	string	Search query (required).
`mode`	string	keyword (default) or semantic. Semantic finds bills about a topic even without shared words; results are relevance-ranked and each row carries a similarity score. Single page, limit ≤ 50.
`state`	string	Two-letter state code.
`status`	string	Filter by canonical status.
`page`	integer	Page number (default 1; keyword mode only).
`limit`	integer	Results per page, 1–100 (default 25).

Example request

curl "https://docketroom.ai/api/v1/search?q=data%20privacy&state=TX" \
  -H "Authorization: Bearer cvts_your_key_here"

Example response

{
  "data": [ { "id": "…", "number": "…", "title": "…", "status": "…" } ],
  "pagination": { "page": 1, "limit": 25, "total": 57, "has_more": true }
}

Errors

Errors return a JSON body { "error": "…" } with one of these status codes:

`401`	Missing/invalid Authorization header, bad key format, or revoked key.
`403`	Key lacks the required scope, or the team does not have API access (Team or Enterprise plan).
`404`	Resource not found (e.g. unknown bill id).
`429`	Rate limit exceeded. See Retry-After and X-RateLimit-* headers.
`500`	Server error while fetching data.

MCP server

Docket Room is also available as a remote Model Context Protocol server, so AI agents (Claude, Cursor, VS Code, and any MCP-capable client) can search bills, read summaries and predictions, and pull roll-call tallies directly. It uses the same team API keys, scopes, and rate limits as the REST API — one request per tool call.

https://docketroom.ai/api/mcp

Tools

search_bills — keyword or bill-number search across all states + Congress (scope: search)
semantic_search_bills — meaning-based topic search with similarity-ranked results (scope: search)
list_bills — filter by state, status, tag, sponsor, or committee (scope: bills)
get_bill — one bill with AI summaries, predictions (incl. trend + model provenance), and hearings (scope: bills)
analyze_bill — structured analysis with quote-verified provisions, dates, agencies, ambiguities (scope: bills)
list_bill_versions / compare_bill_versions — text versions + structured amendment analysis (substantive vs technical, quote-verified) (scope: bills)
get_bill_text — original legislative text, chunked (scope: bills)
get_bill_cosponsors — full cosponsor list (scope: bills)
related_bills — embedding-similar bills: companions, model legislation, other states (scope: bills)
get_bill_votes — per-roll-call tallies with party splits (scope: bills)
recent_changes — what changed across the legislature: actions, statuses, new bills, sponsors (scope: bills)
get_bill_changes — one bill's detected change history (scope: bills)
upcoming_hearings — hearings calendar; filter by state, bill, or tracked=true for your bills (scope: bills)
search_regulations — federal rules by keyword/agency, incl. open comment windows (scope: regulations)
get_regulation — one rule with detail + related bills (scope: regulations)
list_legislators — current members by state/chamber/party (scope: legislators)
track_bill / untrack_bill / update_tracked_bill / list_tracked_bills / tracked_changes — manage your tracked list (incl. position + priority) and get its change digest (scope: tracking; OAuth connections only — API keys carry no user identity)
list_keyword_alerts / create_keyword_alert / delete_keyword_alert — issue-based monitors across jurisdictions (scope: tracking; OAuth only)

Prompts & resources

The server also ships two prompts — bill_brief (stakeholder briefing on one bill) and topic_scan (survey a policy topic) — and a docketroom://bills/{id} resource template for clients that attach resources directly.

Sign in with OAuth (recommended)

Docket Room supports OAuth 2.1 with dynamic client registration, so clients that speak MCP authorization — including claude.ai custom connectors — can connect with a browser sign-in instead of a pasted key: add https://docketroom.ai/api/mcp as a connector and approve the consent screen. OAuth connections act as you (enabling the tracking tools) under your team's plan. Manage or disconnect connected apps anytime in Settings → API.

Claude Code

# OAuth (browser sign-in, user-scoped):
claude mcp add --transport http docketroom https://docketroom.ai/api/mcp

# Or with an API key (team-scoped, no tracking tools):
claude mcp add --transport http docketroom https://docketroom.ai/api/mcp \
  --header "Authorization: Bearer cvts_your_key_here"

Cursor / VS Code (mcp.json)

{
  "mcpServers": {
    "docketroom": {
      "url": "https://docketroom.ai/api/mcp",
      "headers": { "Authorization": "Bearer cvts_your_key_here" }
    }
  }
}

Need higher limits or additional data? Contact us.