# 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).