API documentation — by Values for America

Keys and rate limits

Without a key: 60 requests a minute per client. With a free researcher API key: 600 a minute and 50,000 a day. Send the key in the X-API-Key header; never put it in a URL. Keys apply to endpoints under /api/constitution-index/, /api/constitution/, /api/data/, /api/public/state-of-the-constitution, /api/public/si-response.

curl -H "X-API-Key: vfa_your_key" "https://www.valuesforamerica.com/api/constitution-index/grades.json?type=bill&limit=100"

Errors: 401 unknown or revoked key; 429 limit reached (see Retry-After); 503 publication paused (data withheld); 404 not found; 422 bad parameter.

Response format

JSON responses wrap results in an envelope with attribution, methodology, rubric_version, generated_at, paging fields (count, limit, offset) and data. Dates are ISO 8601 in UTC. Page with limit and offset; for everything at once, use a dataset release (latest: 2026-10).

Constitution Index

Grades of bills and executive orders, and member voting records.

GET /api/constitution-index/coverage.json

Index coverage: measures graded, history kept.

GET /api/constitution-index/grades.json

Current grades, newest first.

Parameters: type=bill|executive_order|all · history=true (include superseded) · since=YYYY-MM-DD · limit (max 1000) · offset

GET /api/constitution-index/grades.csv

The same grades as CSV; each row carries its citation.

Parameters: same as grades.json; limit max 5000

GET /api/constitution-index/grades/{grade_id}.json

One grade version with its five checks, sources and version history.

GET /api/constitution-index/voting-records.json

Constitutional Voting Record per member.

Parameters: eligible_only=true · limit · offset

GET /api/constitution-index/voting-records.csv

The same records as CSV.

Parameters: eligible_only=true

GET /api/constitution-index/voting-records/{actor_id}.json

One member's record with every counted vote and its official roll-call source.

GET /api/constitution-index/voting-records/{actor_id}/congress/{congress}.json

One member's record in one Congress (e.g. 118 for 2023-2024), with every vote.

Constitution Explorer

The full Constitution, provision by provision, with live citations and SI explainers.

GET /api/constitution/provisions.json

Every Article, Section, Clause and Amendment: text, ids and live citation counts.

GET /api/constitution/provisions/{provision_id}.json

One provision (ids like art1-s8-c3, amd14-s1): text, published SI explainer, founding-era sources, leading cases and every item citing it.

Dataset releases

Monthly, immutable snapshots of the whole record.

GET /api/data/releases

Every release with its citation and file count.

GET /api/data/releases/latest

The newest release manifest: files, sizes, row counts, SHA-256, changelog.

GET /api/data/releases/{label}

One release manifest (label: YYYY-MM).

GET /data/releases/{label}/{path}

Download a release file (CSV, JSON, Parquet, data dictionary, checksums). Not rate-limited; cache forever.

Reports

Deterministic reports computed from published records.

GET /api/public/state-of-the-constitution

Weekly State of the Constitution (latest week).

Parameters: week=YYYY-Www · version

GET /api/public/si-response

Same-day SI Response: high-salience bills and executive orders of the last two weeks, with how fast each got its grade and Solution.

Parameters: days (max 60)

Trust and impact

Corrections, audits and the adoption log.

GET /api/trust/corrections

The public corrections log.

GET /api/trust/audit

Weekly audit sample with critic scores and gate pass rates.

GET /api/public/adoption

“Moved toward VFA” entries with verbatim quotes from both texts.

GET /api/public/syndication/feed

Recently published Solutions and SI Think Tank ideas with full public text.

Parameters: limit (max 100)

Attribution and terms

Data is CC BY 4.0: credit “Values for America Constitution Index” and link the grade permalink or release. Grades and Solutions are SI-generated analysis published after automated checks, not individually reviewed by a person, and never an endorsement of a candidate or party. Full terms of use · methodology · how to cite.