Public API · MCP server · Firm-tier keys
The record Clarion tracks — yours to query directly.
/api/v1 and an MCP server serve the same bills, jurisdictions, officials, and GR calendar the product runs on — read-only JSON, no key required to start. A Firm-plan bearer key adds richer payload depth and live, uncached data, bundled at no extra cost.
Quick start
One request. No key.
Every anonymous call is CORS-open and cached at the edge for an hour — point a script, a dashboard, or a newsroom tool at it directly.
Request
curl "https://app.withclarion.com/api/v1/bills?jurisdiction=ca-on&q=housing"Response
{
"count": 2,
"bills": [
{
"slug": "ca-on-bill-64",
"number": "Bill 64",
"titleEn": "Housing Equity and Rental Transparency Act, 2025",
"jurisdictionCode": "ca-on",
"status": "First Reading Ordered for Second Reading",
"lastEventAt": "2025-10-28"
},
{
"slug": "ca-on-bill-28",
"number": "Bill 28",
"titleEn": "Homelessness Ends with Housing Act, 2025",
"jurisdictionCode": "ca-on",
"status": "Second Reading Vote",
"lastEventAt": "2025-10-23"
}
]
}Trimmed for space — the live response also carries titleFr, jurisdictionNameEn/Fr, and level.
Every endpoint self-describes at GET /api/v1 — the full schema is the OpenAPI descriptor.
What's in the record
Seven read endpoints. One shape.
Bills, jurisdictions, the who-to-lobby officials roster, and the unified GR calendar — the same corpora behind the SEO pages, served as clean JSON.
- GET/api/v1/calendar
- Committee meetings, comment deadlines, tender and funding closes, and sitting days, merged soonest-first.
- GET/api/v1/bills
- Every tracked bill, federal and provincial/territorial, most-recently-active first. Filter with ?jurisdiction=, ?status=, ?q=.
- GET/api/v1/bills/{slug}
- One bill: its stage timeline and the transparent, rule-based passage outlook.
- GET/api/v1/jurisdictions
- Every jurisdiction with tracked bills, and its bill count.
- GET/api/v1/jurisdictions/{code}
- One jurisdiction's bill count and most recent bills.
- GET/api/v1/people
- Every tracked elected or appointed official — the who-to-lobby roster.
- GET/api/v1/people/{id}
- One official's record: role, party, contact, sponsored bills, and statements.
Firm-tier keys
Bundled free on Firm. No metered add-on.
Issue a bearer key from Settings → API Keys on any Firm-plan workspace — up to 5 active keys. It authorizes both surfaces on this page: the REST endpoints and the MCP server share one boundary.
Authenticate
curl https://app.withclarion.com/api/v1/bills \
-H "Authorization: Bearer clr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"10,000 requests/day per key, reset at UTC midnight. Over quota: a 429 with a Retry-After header and the same JSON error body every time. Every keyed response carries X-RateLimit-Remaining.
What a key adds
- Three payload caps lift to 200 rows: a bill's stage-event timeline (from 20), a jurisdiction's recent bills (from 25), an official's statements (from 10).
- Responses skip the CDN and read the database on every call — live, not cached up to an hour like the anonymous tier.
- Same field names, same filters. A key changes depth and freshness, never the shape.
MCP server
The same record, as three MCP tools.
One endpoint, stateless — no session to open or close. Point any MCP client at it; add the same bearer key if you have one.
Client config
{
"mcpServers": {
"clarion": {
"url": "https://app.withclarion.com/api/mcp",
"headers": {
"Authorization": "Bearer clr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}The headers block is optional — omit it and the server answers anonymously, at the same limits as an unauthenticated REST call.
Tools
upcoming_calendar
No arguments. Wraps GET /api/v1/calendar.
search_bills(jurisdiction?, status?, q?)
Wraps GET /api/v1/bills with the same three filters.
get_passage_outlook(slug)
Just the outlook — band and reasons — from GET /api/v1/bills/{slug}, so a client doesn't parse the full bill object.
POST https://app.withclarion.com/api/mcp
What's not here
The public record is yours to build on. The analysis stays in Clarion.
This API serves what's already public: bill status and stage timelines, the sitting calendar, the officials roster, and the same rule-based passage outlook published on every bill page. Momentum, access-shift forecasting, stance mapping, and co-lobbying clusters — the read we build by grading every one of those records against dozens of client files at once — stay in the product. Not a missing endpoint. The record is commodity; the graded, cited read of it is the moat.
Frequently asked
Do I need a key to start?
No. Every /api/v1 route and the MCP server answer with no Authorization header — CORS-open, cached at the edge for an hour.
What happens over the daily quota?
A 429 with a Retry-After header counting down to the next UTC midnight, and the same JSON error body every time — never a silent drop.
Will v1 change under me?
v1 is stable. A breaking change ships under a new version — v1 never changes shape in place.
Is there a client library?
No SDK. It's plain JSON over HTTP and a standard MCP server — the fetch client or MCP client you already use works today.
The weekly read
Get The Dispatch in your inbox
One email a week: the bills gaining momentum, who's lobbying whom, and the passage odds that moved — across Parliament, the legislatures, and city hall. Free, in English or French.
See last week's issue →Bearer keys are bundled on Firm. Not a metered add-on.
$1,200 a month, Canadian dollars, on the website — 15 users, unlimited topics, and the API + MCP access that lets your own tools read the record directly.