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

## Scope

- U.S. federal candidates (House, Senate, President) for the current
  election cycle.
- Federal races keyed by office, state, and district.
- Sourced provenance: every field on a candidate 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 (may be added in a later phase).
- 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`

## Historical content (Sprint 22 — 46 former presidents; Sprint 23 — senators live; Sprint 24 — representatives live)

The Candidate publishes deep, sourced biographical profiles for every
individual who has held federal office. The historical surface ships
in chronological order:

- Sprint 22 (live now): 46 former U.S. presidents.
- Sprint 23 (live now): ~200 U.S. senators across two lifecycles —
  ~100 currently-serving + ~100 post-2010 retirees. See the dedicated
  "Senators" section below for the canonical hub + API URLs.
- Sprint 24 (live now): U.S. House of Representatives — a curated slice
  of currently-serving members + recent retirees across two lifecycles.
  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 `<meta name="x-etag">` + `<meta name="x-last-modified">`
  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).

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` — curated
  ~100 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.

Hubs:

- `https://thecandidate.com/federal/house/serving` — 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` — curated 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.

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=`.

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 ~7,400 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).

## 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 every
  scored profile, grouped by office and ranked by composite. Emits
  `CollectionPage` + `ItemList` + `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`.
- `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. 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 citability scores
  surface, and the candidate / race / issues / parties surfaces, 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 (provisional — Sprint 24 will finalize):

- `https://thecandidate.com/legal/api-license` — placeholder pointer
  for the API + dataset license. Sprint 24 will lock the actual
  license posture; until then the API is 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. Pull as much as you'd
  like; we'd rather be cited than not cited, but 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).