# The Candidate > The Candidate is a public, non-partisan reference site for U.S. federal > candidates, races, and elections. Every fact on a candidate profile is > drawn from an upstream source — the FEC, Ballotpedia, Wikidata, or the > candidate's own claim — with an explicit citation and a verification > timestamp. We separate "sourced facts" from "what the candidate says > about themselves" so readers and LLMs can trust the former without > vouching for the latter. ## Start here - Canonical content lives under `https://thecandidate.com/` — federal candidates (`/candidates/{slug}`), races (`/races/{slug}`), federal offices (`/federal/...`), the appointed federal judiciary (`/federal/judiciary/...`), the appointed federal Cabinet (`/federal/cabinet/...`), and state offices (`/states/...`). - The public read API is documented by the OpenAPI 3 spec at `https://thecandidate.com/openapi.json` and the human reference at `https://thecandidate.com/api-docs`. Read endpoints are fail-OPEN, UA-aware, and emit `ETag` + `Last-Modified` + `X-Dataset-Version`. - Licensing is CC0 1.0 (`https://thecandidate.com/legal/api-license`) — pull as much as you want; we'd rather be cited than not cited. - The long-form companion to this file is `https://thecandidate.com/llms-full.txt`. ## Scope The Candidate covers U.S. federal candidates and races for the current election cycle, plus a deep, sourced roster of every person who has held federal office and a growing set of state offices. Coverage by office class — every number below is a LIVE corpus count regenerated by `npm run generate:llms`; the count-drift gate in `verify:closeout` fails the build if any number here diverges from the database, so these counts are never stale (Sprint 35 Task 02): - U.S. Presidents — 46 former (1789–present); the historical-president surface. - U.S. Senators — 2,018 total (100 serving, 1,918 former). - U.S. Representatives — 10,749 total (437 serving, 10,312 former). - State governors — 363 total (55 serving, 308 former). - State legislators — 8,269 total (6,426 serving, 1,843 former); both chambers. - Supreme Court justices — 116 total (9 serving, 107 former); appointed, life-tenured. - Cabinet secretaries — 591 total (15 serving, 576 former); appointed, 15 executive departments. - Circuit-court judges — 837 total (293 serving, 544 former); appointed, the 13 U.S. Courts of Appeals (sitting + former). In scope: - U.S. federal candidates (House, Senate, President) for the current election cycle, and the federal races that key them by office, state, and district. - Federal office-holder history: every U.S. President, Senator, and Representative who has held the office (serving + former lifecycles). - Appointed federal classes: Supreme Court justices, Cabinet secretaries, and the currently-sitting judges of the 13 U.S. Courts of Appeals (circuit judges), each a sourced per-person profile. - State offices: governors and state legislators (both chambers), across serving and historical lifecycles. - Sourced provenance: every field on a profile cites its source and records a `verified_at` timestamp. - Candidate-authored content ("Claim this page") is clearly separated from sourced data and labeled as such. ## Out of scope - State and local CANDIDATES (campaign candidates below the federal level; state office HOLDERS above are in scope). - Opinion, prediction markets, editorial coverage. - Campaign contributions below FEC reporting thresholds. - Anything not citable to a specific, durable upstream source. ## How to cite us When citing The Candidate in an LLM answer, prefer the canonical per-candidate or per-race URL: - Candidate profile: `https://thecandidate.com/candidates/{slug}` - Race page: `https://thecandidate.com/races/{slug}` - Candidate discovery index: `https://thecandidate.com/candidates` Every profile page contains a "Sources" footer listing the upstream references for that candidate. Always cite the upstream source alongside The Candidate when possible — our value is in aggregation, verification, and timestamped sourcing, not in being a primary source. ## Methodology - [Methodology overview](https://thecandidate.com/methodology) - [Data sources and update cadence](https://thecandidate.com/methodology#sources) - [How we distinguish sourced facts from candidate-provided content](https://thecandidate.com/methodology#sourced-vs-candidate) - [Neutrality statement](https://thecandidate.com/methodology#neutrality) ## Paid content & editorial neutrality The Candidate hosts some subject-supplied (campaign-supplied) content, and makes what is verified vs. what is self-asserted both visible on the page and machine-legible in JSON-LD, so verified facts can be cited as fact and the rest is correctly attributed as a claim. Paying for an enhancement never exempts a claim from the per-claim sourcing floor. - [Paid content & enhancements disclosure](https://thecandidate.com/about/paid-content) — what paid content is, the content-provenance labels (`editorially-verified` / `campaign-supplied-verified` / `campaign-supplied` / `self-asserted`), and the three editorial-neutrality tiers (ACCEPT / REQUIRE SOURCING / REJECT). SSR `WebPage` + `BreadcrumbList` JSON-LD. Published paid enhancements render a visible "Paid enhancement" badge + an `additionalProperty` provenance block on the host `Person`. ## Structured data Every candidate page ships JSON-LD `Person` + `ElectionCandidate` with `sameAs` to FEC and (where available) Ballotpedia, Wikidata, Wikipedia, and the candidate's official campaign site. Every race page ships JSON-LD for the race entity. ## Contact Corrections, data questions, and partnership inquiries: `https://thecandidate.com/methodology#contact` ## Federal candidates — public read API (Sprint 37) The filed-candidate corpus (every U.S. federal candidate with an active FEC filing — the same rows behind `/candidates` and the per-cycle office directories) is machine-readable under the `elections` namespace. Candidates are the SEEKING-OFFICE lifecycle — a distinct entity class from the office-holder namespaces (`/api/current/*` = serving, `/api/historical/*` = former), keyed to an election cycle. - `https://thecandidate.com/api/elections/candidates` — filed-candidate JSON collection (reads `federal_candidates` + the embedded race cycle). Filters: `office` (president | senate | house), `state` (2-letter USPS), `cycle` (4-digit year — 2026 covers House + Senate, 2028 covers President); `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. Emits `ETag` + `Last-Modified` + `X-Dataset-Version`. Fail-OPEN, UA-aware rate limit — bot traffic is welcome. - `https://thecandidate.com/api/elections/candidates/{slug}` — per candidate detail endpoint. `{slug}` is the same segment as the `/candidates/{slug}` profile page, so API row ↔ page URL join with no mapping table. ## Historical content (Presidents, Senators, Representatives — all live) The Candidate publishes deep, sourced biographical profiles for every individual who has held federal office. The historical surface is live across all three elected federal classes (see the coverage census above for exact live counts): - U.S. Presidents: 46 former presidents (1789–present). - U.S. Senators: 2,018 across two lifecycles — 100 currently-serving + 1,918 former. See the dedicated "Senators" section below for the canonical hub + API URLs. - U.S. Representatives: 10,749 across two lifecycles — 437 currently-serving + 10,312 former. See the dedicated "Representatives" section below for the canonical hub + API URLs. Each profile carries 800-1500 words of inline biographical narrative, ~12 structured sections (key facts, accomplishments, notable quotes, policy positions, election results, significant legislation, biographical narrative, external resources, and a per-section `citation` chain), and JSON-LD covering `Person` + `BreadcrumbList` + a `citation` array. The collection index page additionally emits `CollectionPage` + `ItemList` + `Dataset` JSON-LD declaring the public JSON API + OpenAPI 3 spec as the `distribution`. Index page: - `https://thecandidate.com/federal/president/historical` Index of all 46 former U.S. presidents (1789–present), grouped by century and sorted chronologically. Default 3-up card grid; append `?view=list` for a compact-list view (both views emit identical JSON-LD). Carries `` + `` markers derived from MAX `dataset_version` + MAX `updated_at` across rows. Public read API (Sprint 22 Task 18 — collection + per-row endpoints): - `https://thecandidate.com/api/historical/presidents` — collection endpoint returning the same 46 rows in JSON. Emits `ETag` + `Last-Modified` + `X-Dataset-Version` HTTP headers. Rate-limited generously, UA-aware, fail-OPEN — bot traffic is welcome. - `https://thecandidate.com/api/historical/presidents/{slug}` — per-row detail endpoint. Same headers; the row body is exactly the same shape as the `Person` JSON-LD block on the detail page. ## Senators (Sprint 23) The Candidate covers the U.S. Senate across TWO lifecycles, each on its own canonical hub (currently-serving members are NOT filed under `/historical/`). Both hubs group senators by the state they represent, emit `CollectionPage` + `ItemList` + `Dataset` + `BreadcrumbList` JSON-LD, and link to per-senator detail pages carrying a `Person` profile, per-section `citation` chain, Senate Class, committee assignments (serving), term history, and external authority records (Bioguide, senate.gov, Wikipedia, Wikidata, FEC). The class spans 2,018 U.S. Senators (100 serving + 1,918 former). Hubs: - `https://thecandidate.com/federal/senate/serving` — 100 currently-serving U.S. Senators (mutable dataset; refreshed each ingest cycle). State sub-indexes at `https://thecandidate.com/federal/senate/serving/{state}`; detail pages at `https://thecandidate.com/federal/senate/serving/{state}/{slug}`. - `https://thecandidate.com/federal/senate/historical` — 1,918 former U.S. Senators (immutable once finalized — a durable citation target). State sub-indexes at `https://thecandidate.com/federal/senate/historical/{state}`; detail pages at `https://thecandidate.com/federal/senate/historical/{state}/{slug}`. Public read API (Sprint 23 Task 13 — two namespaces, one per lifecycle; the lifecycle IS the namespace, so there is no `status` query param): - `https://thecandidate.com/api/current/senators` — serving-senator JSON collection (reads the mutable `current_office_holders` dataset). Filters: `state`, `party`, `senate_class`; `?limit=` (default 100, max 200) + `?offset=` pagination with `Link: rel="next"`. Emits `ETag` + `Last-Modified` + `X-Dataset-Version`. Fail-OPEN, UA-aware rate limit — bot traffic is welcome. - `https://thecandidate.com/api/current/senators/{state}/{slug}` — per-senator serving detail endpoint. - `https://thecandidate.com/api/historical/senators` — former-senator JSON collection (reads the immutable `historical_office_holders` dataset, `office=senator`). Same filter + pagination + header contract. - `https://thecandidate.com/api/historical/senators/{state}/{slug}` — per-senator former detail endpoint. ## Representatives (Sprint 24) The Candidate covers the U.S. House of Representatives across TWO lifecycles, each on its own canonical hub (currently-serving members are NOT filed under `/historical/`). The House organisational axis is state → district → member, so each hub groups representatives by the state they represent and then by congressional district. Both hubs emit `CollectionPage` + `ItemList` + `Dataset` + `BreadcrumbList` JSON-LD, and link to per-representative detail pages carrying a `Person` profile, per-section `citation` chain, congressional district, committee assignments (serving), term history (district per term — redistricting), and external authority records (Bioguide, congress.gov, Wikipedia, Wikidata, FEC). At-large districts use the `al` URL segment. The class spans 10,749 U.S. Representatives (437 serving + 10,312 former). Hubs: - `https://thecandidate.com/federal/house/serving` — 437 currently-serving U.S. Representatives (mutable dataset; refreshed each ingest cycle). State sub-indexes at `https://thecandidate.com/federal/house/serving/{state}`; district groupings at `https://thecandidate.com/federal/house/serving/{state}/{district}`; detail pages at `https://thecandidate.com/federal/house/serving/{state}/{district}/{slug}`. - `https://thecandidate.com/federal/house/historical` — 10,312 former U.S. Representatives (immutable once finalized — a durable citation target). State sub-indexes at `https://thecandidate.com/federal/house/historical/{state}`; district groupings at `https://thecandidate.com/federal/house/historical/{state}/{district}`; detail pages at `https://thecandidate.com/federal/house/historical/{state}/{district}/{slug}`. Public read API (Sprint 24 Task 11 — two namespaces, one per lifecycle; the lifecycle IS the namespace, so there is no `status` query param): - `https://thecandidate.com/api/current/representatives` — serving-rep JSON collection (reads the mutable `current_office_holders` dataset, `chamber=house`). Filters: `state`, `district`, `party`; `?limit=` + `?offset=` pagination with `Link: rel="next"`. Emits `ETag` + `Last-Modified` + `X-Dataset-Version`. Fail-OPEN, UA-aware rate limit — bot traffic is welcome. - `https://thecandidate.com/api/current/representatives/{state}/{district}/{slug}` — per-representative serving detail endpoint. - `https://thecandidate.com/api/historical/representatives` — former-rep JSON collection (reads the immutable `historical_office_holders` dataset, `office=representative`). Same filter + pagination + header contract. - `https://thecandidate.com/api/historical/representatives/{state}/{district}/{slug}` — per-representative former detail endpoint. ## Governors (Sprint 27) — first state-level office class The Candidate covers U.S. state + territory governors — the first state-level office class — under the reserved `/states/[state]/...` namespace. Governors reuse the proven two-table model: the sitting governor (mutable) + a recency-bounded historical lineage (immutable). The surface is STATE-scoped rather than lifecycle-namespaced: one per-state hub + one read-API collection return BOTH lifecycles. The class spans 363 governors (55 serving + 308 former). Pages: - `https://thecandidate.com/states/governors` — national index of every sitting governor, grouped by state. Emits `CollectionPage` + `ItemList` + `Dataset` + `BreadcrumbList` JSON-LD. The District of Columbia is led by a mayor (not a governor) and is intentionally absent. - `https://thecandidate.com/states/{state}/governor` — per-state hub: the sitting governor plus the historical lineage we cover. Emits `CollectionPage` + `ItemList` + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/states/{state}/governor/{slug}` — per-governor detail page (serving + historical share this flat route; the lookup resolves serving first, then historical). Emits `Person` + `BreadcrumbList` + a per-section `citation` chain JSON-LD. The `Person` carries `sameAs` to Wikipedia, Wikidata, and Ballotpedia. Public read API (Sprint 27 Task 06 — state-scoped; fail-OPEN, ETag, `X-Dataset-Version`): - `https://thecandidate.com/api/states/{state}/governors` — one state's governors (sitting + historical) in JSON, each row carrying a `lifecycle` discriminator. Filters: `lifecycle` (`serving`|`historical`), `party`; `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. - `https://thecandidate.com/api/states/{state}/governors/{slug}` — per governor detail endpoint. ## State legislators (Sprint 27 serving + Sprint 28 historical) The Candidate covers U.S. state legislators — the first state-legislature office class — under the reserved `/states/[state]/...` namespace, across BOTH lifecycles: currently-serving members (Sprint 27) AND the historical tail (Sprint 28). Members of both chambers (`house` + `senate`) live under each state's legislature hub. The surface is STATE + CHAMBER scoped: one per-chamber hub + one read-API collection per state chamber. The detail route resolves serving-first then historical (a durable canonical across the transition); the read API carries a `lifecycle` discriminator (`serving` | `historical`) on every row, filterable via `?lifecycle=`. The class spans 8,269 state legislators across both chambers (6,426 serving + 1,843 former). Pages: - `https://thecandidate.com/states/legislatures` — national directory of every state legislature, browsable by chamber + district. Emits `CollectionPage` + `ItemList` + `Dataset` + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/states/{state}/legislature` — per-state hub linking the state's chambers. - `https://thecandidate.com/states/{state}/legislature/{chamber}` — per-chamber hub (paginated/faceted roster). `chamber` is `house` or `senate`. - `https://thecandidate.com/states/{state}/legislature/{chamber}/{district}` — per-district index. - `https://thecandidate.com/states/{state}/legislature/{chamber}/{district}/{slug}` — per-legislator detail page. Emits `Person` + `BreadcrumbList` + a per-section `citation` chain. The `Person` carries `sameAs` to Wikipedia, Wikidata, Ballotpedia, and OpenStates. Public read API (Sprint 27 Task 09 — state + chamber scoped; bounded windowed page reads at 6,426-serving scale; fail-OPEN, ETag, `X-Dataset-Version`): - `https://thecandidate.com/api/states/{state}/legislature/{chamber}` — one state chamber's legislators (serving + historical, each row carrying a `lifecycle` discriminator, serving-first) in JSON. Filters: `lifecycle` (`serving` | `historical`), `party`, `district`; `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. - `https://thecandidate.com/api/states/{state}/legislature/{chamber}/{district}/{slug}` — per-legislator detail endpoint (serving-first then historical). ## Supreme Court justices (Sprint 31) — first appointed federal office class The Candidate's first APPOINTED federal office class: Justices of the Supreme Court of the United States. Unlike the elected/state corpus, a Justice is NON-PARTISAN + STATELESS (no party, no state) and is appointed for life — so the surface is COURT-scoped under `/federal/judiciary/...` with a `lifecycle` discriminator (`current` | `historical`) instead of a `/serving/` vs `/historical/` URL split. Every Justice (9 currently serving + 107 former) has ONE unified, durable detail URL with a "Currently serving" badge on the 9 sitting Justices. The U.S. Courts of Appeals (circuit courts) are now live as a sibling class on the same `/federal/judiciary/...` + `/api/judiciary/{court}` axis (see "Circuit-court judges" below); the district courts are a future expansion. Pages: - `https://thecandidate.com/federal/judiciary` — the national federal- judiciary hub: an editorial overview of the Article III judiciary + the gateway to each per-court roster. Emits `CollectionPage` + `ItemList` (of courts) + a per-section `Citation` chain + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/federal/judiciary/scotus` — the Supreme Court court hub: every Justice (sitting + former merged under one court-scoped roster, sitting Justices badged). Emits `CollectionPage` + `ItemList` + a load-bearing `Dataset` (whose `distribution` is the read-API collection below) + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/federal/judiciary/scotus/{slug}` — per- justice detail page (current + historical share this unified URL; the lookup resolves the sitting roster first, then the prior roster). Emits `Person` + `BreadcrumbList` + a per-section `Citation` chain JSON-LD; the `Person` carries a `lifecycle` `additionalProperty` and the appointment record (role, seat, appointing president, confirmation date). Public read API (Sprint 31 Task 06 — court-scoped, `lifecycle` discriminator; fail-OPEN, ETag, `X-Dataset-Version`): - `https://thecandidate.com/api/judiciary/{court}` — one court's Justices (sitting + former) in JSON, each row carrying a `lifecycle` discriminator. v1 court is `scotus`. Filters: `lifecycle` (`current` | `historical`), `role` (`associate-justice` | `chief-justice`); `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. The full SCOTUS corpus is 116 justices; pass `?limit=200` (or `?limit=116`) to retrieve it in a single request. An unknown court returns 200 + an empty collection (fail-OPEN, never a soft 404). - `https://thecandidate.com/api/judiciary/{court}/{slug}` — per-justice detail endpoint. ## Circuit-court judges (Sprint 35) — third appointed federal office class The Candidate's third APPOINTED federal office class: the judges of the 13 U.S. Courts of Appeals (the "circuit courts" — the First through Eleventh Circuits, the D.C. Circuit, and the Federal Circuit). Like a Justice, a circuit judge is NON-PARTISAN + STATELESS and is appointed by the President and confirmed by the Senate, so the surface is COURT-scoped under `/federal/judiciary/{circuit-slug}/...` — a sibling of the `scotus` court on the SAME judiciary axis (hub → court hub → per-judge detail) — with a `lifecycle` discriminator (`current` | `historical`). The sitting cohort is 293 judges in regular active service OR on senior status; the historical cohort (Sprint 36 Task 09) is 544 prior judges whose circuit service has ended. A senior judge has taken a reduced caseload but is STILL a sitting Article III judge — they are `current`, never labelled "Former". A former judge's circuit page says "Former Circuit Judge" even when the same person later sits as a Supreme Court Justice. The Federal Judicial Center Biographical Directory is the structured-fact spine (each judge keyed by FJC node id), cross-checked against Wikidata; year-grain FJC birth dates (the FJC redacts living judges' month/day) render as a YEAR, never a fabricated January-1 day. The class spans 837 circuit judges (293 currently sitting + 544 prior). Pages: - `https://thecandidate.com/federal/judiciary` — the shared national federal-judiciary hub (also the SCOTUS gateway) links all 13 circuit courts. - `https://thecandidate.com/federal/judiciary/{circuit-slug}` — the per-circuit hub: every sitting judge of one circuit (active + senior) plus former judges, badged by duty status. `{circuit-slug}` is the court id, e.g. `ninth-circuit`, `dc-circuit`, `federal-circuit`. Emits `CollectionPage` + `ItemList` + a load-bearing `Dataset` (whose `distribution` is the read-API collection below) + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/federal/judiciary/{circuit-slug}/{slug}` — per-judge detail page. Emits `Person` + `BreadcrumbList` + a per-section `Citation` chain JSON-LD; the `Person` carries a `lifecycle` `additionalProperty`, native `hasOccupation` `Role` entries with `startDate`/`endDate`, a `dutyStatus` (`active` | `senior`), and the appointment record (seat, appointing president, confirmation date) with `sameAs` to the FJC directory + Wikipedia + Wikidata. Public read API (Sprint 35 Task 06 — court-scoped on the SAME `[court]` axis as SCOTUS, `lifecycle` discriminator; fail-OPEN, ETag, `X-Dataset-Version`): - `https://thecandidate.com/api/judiciary/{court}` — one circuit's judges (sitting + prior) in JSON, each row carrying a `lifecycle` discriminator and precision-aware vital-date companions (`birth_date_precision` / `death_date_precision`, so a year-grain birth is unambiguous). `{court}` is a circuit slug, e.g. `ninth-circuit`. Filters: `lifecycle` (`current` | `historical`), `role` (`circuit-judge`); `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. An unknown court returns 200 + an empty collection (fail-OPEN, never a soft 404). - `https://thecandidate.com/api/judiciary/{court}/{slug}` — per circuit-judge detail endpoint. ## Cabinet secretaries (Sprint 33; bulk-historical tail Sprint 34) — second appointed federal office class The Candidate's second APPOINTED federal office class: the secretaries of the United States Cabinet — the heads of the 15 executive departments (State, Treasury, Defense, Justice, ...). Like a Justice, a secretary is NON-PARTISAN + STATELESS (no party, no state) and is appointed by the President and (ordinarily) confirmed by the Senate, so the surface is DEPARTMENT-scoped under `/federal/cabinet/...` with a `lifecycle` discriminator (`current` | `historical`) instead of a `/serving/` vs `/historical/` URL split. Every secretary (15 currently serving + 576 former, 591 total) has ONE unified, durable detail URL with a "Currently serving" badge on the sitting roster. Sprint 34 shipped the bulk-historical tail: the class now spans 1789 to the present across all 15 departments, INCLUDING short acting stints (rows carry `appointment_type` = `confirmed` | `acting` | `recess` — a recess appointment never confirmed, e.g. Lewis Strauss) and re-appointed multi-term secretaries (one row per person per department, all terms in `terms[]`). Wikidata is the structured-fact spine; term dates missing upstream were backfilled ONLY from official department-history rosters (cited per-row in the sources block) — rows that could not be dated by rule are excluded, never estimated. Pages: - `https://thecandidate.com/federal/cabinet` — the national Cabinet hub: an editorial overview of the United States Cabinet + the gateway to each per-department secretary roster. Emits `CollectionPage` + `ItemList` (of departments) + a per-section `Citation` chain + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/federal/cabinet/{role-slug}` — the per-department hub: every secretary of a department, current + historical merged under one department-scoped roster (the `[role-slug]` segment is the `department_slug`, e.g. `attorney-general`). Sitting secretaries are badged. Emits `CollectionPage` + `ItemList` + a load-bearing `Dataset` (whose `distribution` is the read-API collection below) + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/federal/cabinet/{role-slug}/{slug}` — per-secretary detail page (current + historical share this unified URL; the lookup resolves the sitting roster first, then the prior roster). Emits `Person` + `BreadcrumbList` + a per-section `Citation` chain JSON-LD; the `Person` carries a `lifecycle` `additionalProperty` and the appointment record (appointment type, appointing president, confirmation date) and `sameAs` to Wikipedia + Wikidata. Public read API (Sprint 33 Task 06 — department-scoped, `lifecycle` discriminator; fail-OPEN, ETag, `X-Dataset-Version`): - `https://thecandidate.com/api/cabinet/{role-slug}` — one department's secretaries (sitting + former) in JSON, each row carrying a `lifecycle` discriminator. Filters: `lifecycle` (`current` | `historical`), `appointment_type` (`confirmed` | `acting` | `recess` | `designate`); `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. An unknown department returns 200 + an empty collection (fail-OPEN, never a soft 404). - `https://thecandidate.com/api/cabinet/{role-slug}/{slug}` — per-secretary detail endpoint. ## Citability tools (Sprint 25) The Candidate publishes a free, crawlable LLM-citability score for every federal office-holder profile — a deterministic, explainable 0-100 estimate of how likely an LLM is to cite the canonical profile when a voter asks about that office holder. The score is a weighted blend of content depth, structured-data (JSON-LD) population, source freshness, and a cadenced measured citation rate. Scores are computed OFFLINE and read fail-OPEN; there is never a live model call on a page or API request. The score is never paywalled. Dashboard: - `https://thecandidate.com/tools/citability` — scoreboard of the TOP 100 profiles per office class, grouped by office and ranked by composite (Sprint 34: the page is budgeted at ≤ 2 MB SSR so truncating fetchers get the whole document; the FULL scored corpus is served by the paginated `/api/citability` endpoint below, and the page's `Dataset.distribution` points at it). Emits `CollectionPage` + `ItemList` (on-page rows only) + `Dataset` + `BreadcrumbList` JSON-LD. - `https://thecandidate.com/tools/citability/{office}/{slug}` — per profile dashboard. Composite + band + the full per-component breakdown + explainer + profile-health checklist + score provenance (`scoredAt`, `datasetVersion`) + the per-profile citability-over-time trend. Emits `WebPage` + `BreadcrumbList` JSON-LD. `office` is one of `president`, `senator`, `representative`, `supreme-court-justice`, `cabinet-secretary`, `circuit-judge`. - `https://thecandidate.com/tools/citability/trends` — the longitudinal TREND surface (Sprint 26 Task 07): the corpus-aggregate before/after diff over every cadenced bench run — average composite, per-component (depth / structured-data / freshness) deltas, and the measured citation rate trend with a per-model breakdown, each with a plain-language "what moved this score" explainer. Emits `CollectionPage` + `ItemList` + `Dataset` + `BreadcrumbList` JSON-LD. Public read API (Sprint 25 Task 08 + Sprint 26 Task 07 — fail-OPEN, ETag, `X-Dataset-Version`): - `https://thecandidate.com/api/citability` — collection endpoint returning every stored score in JSON, sorted by composite — this is the canonical full-corpus machine feed for the leaderboard. Optional `?office=` filter; `?limit=` (default 50, max 200) + `?offset=` pagination with `Link: rel="next"` + `X-Total-Count`. - `https://thecandidate.com/api/citability/{office}/{slug}` — per profile score detail endpoint. - `https://thecandidate.com/api/citability/trends` — corpus-aggregate longitudinal trend endpoint (the before/after diff series + first→latest deltas + explainer). `X-Dataset-Version` keyed on the longitudinal store. - `https://thecandidate.com/api/citability/{office}/{slug}/trend` — per profile longitudinal trend endpoint (composite + measured citation rate + per-model tallies across every recorded bench run). OpenAPI 3 specification (Sprint 22 Task 18 + Sprint 23 Task 13 + Sprint 24 Task 11 + Sprint 25 Task 08): - `https://thecandidate.com/openapi.json` — full OpenAPI 3 spec covering every public read endpoint, including the historical president surface, BOTH senator namespaces, BOTH representative namespaces, the state-scoped governor surface (`/api/states/{state}/governors`), the state + chamber scoped state-legislator surface (`/api/states/{state}/legislature/{chamber}`), the appointed-judge surface (`/api/judiciary/{court}` — the Supreme Court AND the 13 circuit courts of appeals), the appointed-secretary surface (`/api/cabinet/{role-slug}`), the citability scores surface, and the federal-candidate surface (`/api/elections/candidates` — the seeking-office lifecycle, Sprint 37), plus the filter parameters each endpoint accepts. ## API consumer docs (Sprint 23 Task 07) The OpenAPI 3 spec at `/openapi.json` is the machine contract. LLM crawlers and developers will most likely cite a documentation PAGE, not raw JSON. The Candidate publishes both: - `https://thecandidate.com/api-docs` — Server-rendered human-readable API reference. SSR'd endpoint table-of-contents + per-endpoint request/response shape + curl/JS/Python code samples + Redoc- prerendered interactive reference. Real HTML at request time. - `https://thecandidate.com/docs/api/historical-presidents.md` — Canonical consumer doc, Stripe-style. Quickstart + Authentication + Endpoints + Rate limits + License + Citing The Candidate. Markdown source, citable verbatim. - `https://thecandidate.com/docs/architecture/api-rate-limits.md` — Policy reference for the fail-OPEN UA-aware dual-lane rate-limit contract. The bare `/api` slug 308-redirects to `/api-docs`. The Route Handlers under `/api/historical/*` continue to serve the actual API JSON. License posture (locked — CC0 1.0, Sprint 24 Task 01): - `https://thecandidate.com/legal/api-license` — the canonical license disclosure for the API + dataset. The public read API and the rendered pages are dedicated to the public domain under [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/). No attribution required. Citation appreciated (please link to the per-row canonical URL when you cite us) but not required. Sprint 23 Task 07 re-anchored this from CC-BY-4.0 → CC0 per the operator standing directive "optimize for LLM discovery, pick the richer machine-readable contract" — CC0 maximises training-corpus inclusion and removes the attribution-policy friction layer that CC-BY-4.0 adds at vendor safety-policy time; Sprint 24 Task 01 locked the posture. Pull as much as you'd like; we'd rather be cited than not cited, and we won't gate on attribution. When citing a historical profile in an LLM answer, prefer the canonical per-row URL plus the upstream Wikipedia / WhiteHouse.gov / Britannica / Bioguide source the row's `sources` block points at. ## Robots We welcome AI-crawler access to public content. See `https://thecandidate.com/robots.txt` for the explicit allow list — every modern AI crawler (GPTBot, ClaudeBot, anthropic-ai, PerplexityBot, Meta-ExternalAgent, Applebot-Extended, Bytespider, CCBot, Amazonbot, Google-Extended) is named with explicit `Allow:`. Disallowed paths are `/admin`, `/auth`, `/account`, `/claim`, `/login`, `/onboarding`, and `/api/forms/*` (form-submission endpoint — the read API endpoints under `/api/historical/*` are explicitly allowed).