# The Candidate — long-form LLM-discovery pointer

This file is the expanded companion to /llms.txt. Both files target
modern AI crawlers + agentic-fetch tooling that prefers an
authoritative-text pointer over scraping the rendered HTML.

## What thecandidate.com publishes

The Candidate is a neutral, public reference site for U.S. federal
candidates, races, elections, and federal-office-holder history. Every
sourced fact carries an inline citation and a verification timestamp.
Candidate-authored content ("Claim this page") is clearly separated
from sourced content and labeled as such.

## Scope — coverage census (live corpus counts)

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

## Canonical URL families

- Federal candidate profile: https://thecandidate.com/candidates/{slug}
- Federal race page:         https://thecandidate.com/races/{slug}
- Office hub:                https://thecandidate.com/federal/{president|senate|house}
- Office directory (cycle):  https://thecandidate.com/federal/{office}/{cycle-year}/candidates
- Federal judiciary:         https://thecandidate.com/federal/judiciary/{court}/{judge-slug}  (court = scotus or a circuit slug)
- Federal cabinet:           https://thecandidate.com/federal/cabinet/{role-slug}/{secretary-slug}
- State directory:           https://thecandidate.com/states/{state-code}
- Issue taxonomy:            https://thecandidate.com/issues/{slug}
- Federal party directory:   https://thecandidate.com/parties/{party-slug}
- Methodology + sourcing:    https://thecandidate.com/methodology
- About + corrections:       https://thecandidate.com/about
- Comparison tool:           https://thecandidate.com/compare?a=&b=  (noindex, follow)

Bare slugs /president, /senate, /house are standalone Next-rendered
SEO landing pages. They are the SOLE exception to the /federal/
prefix rule for federal coverage.

## Historical content (Presidents, Senators, Representatives — all live)

The Candidate publishes deep, sourced biographical profiles for every
individual who has held federal office. All three elected federal classes
are live across both lifecycles (serving + former); the exact live counts
are in the coverage census above:

- U.S. Presidents: 46 former presidents (1789–present).
- U.S. Senators: 2,018 (100 currently-serving +
  1,918 former).
- U.S. Representatives: 10,749 (437
  currently-serving + 10,312 former).

Each historical 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 JSON-LD
covering Person + BreadcrumbList + a per-section Citation chain.

Historical-content 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. Emits CollectionPage + ItemList
  + Dataset + BreadcrumbList JSON-LD.

Historical-content detail pages:
- https://thecandidate.com/federal/president/historical/{slug}
  Per-row biographical profile. Emits Person + BreadcrumbList +
  Citation chain JSON-LD. Carries <meta name="x-etag"> + <meta
  name="x-last-modified"> markers for clients that prefer in-document
  validators.

## Public read API (Sprint 22 Task 18)

The historical-content surface exposes a documented JSON read API
alongside the rendered HTML. Both surfaces share the same row shape:

- https://thecandidate.com/api/historical/presidents
  Collection endpoint. Returns the 46 rows in JSON.
  Query parameters: ?page=N (1-indexed) and ?per_page=N (max 100,
  default 46). Emits ETag + Last-Modified + Cache-Control +
  X-Dataset-Version + Link headers. Conditional If-None-Match /
  If-Modified-Since return 304.

- https://thecandidate.com/api/historical/presidents/{slug}
  Per-row detail endpoint. Returns one row. Same header set as the
  collection endpoint. 404 + ErrorResponse envelope on slug miss.

## Citability tools (Sprint 25 Task 08)

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.
The composite is a weighted blend of content depth (30%),
structured-data / JSON-LD population (25%), source freshness (15%), and
a cadenced measured citation rate (30%). 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.

- 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 + per-component breakdown +
  explainer + profile-health checklist + score provenance. Emits
  WebPage + BreadcrumbList JSON-LD. office = president | senator |
  representative | supreme-court-justice | cabinet-secretary |
  circuit-judge.
- https://thecandidate.com/tools/citability/trends
  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.
- https://thecandidate.com/api/citability
  Read API collection endpoint (JSON). Optional ?office= filter;
  ?limit= + ?offset= pagination with Link: rel="next". Emits ETag +
  Last-Modified + X-Dataset-Version. Fail-OPEN, UA-aware rate limit.
- https://thecandidate.com/api/citability/{office}/{slug}
  Per-profile score detail endpoint.
- https://thecandidate.com/api/citability/trends
  Corpus-aggregate longitudinal trend endpoint (Sprint 26 Task 07): the
  before/after diff series + first->latest deltas + explainer. ETag +
  X-Dataset-Version keyed on the append-only 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.

## State governors (Sprint 27 Task 06)

The Candidate's first state-level office class: U.S. state + territory
governors, under the reserved /states/[state]/... namespace. The class
spans 363 governors (55 serving +
308 former). Governors reuse the two-table model
(sitting governor + a recency-bounded historical lineage). The surface is
STATE-scoped rather than lifecycle-namespaced — one per-state hub and one
read-API collection return BOTH lifecycles, each row carrying a
"lifecycle" discriminator. The District of Columbia is led by a mayor
(not a governor) and is intentionally excluded.

- https://thecandidate.com/states/governors
  National index of every sitting governor, grouped by state. Emits
  CollectionPage + ItemList + Dataset + BreadcrumbList JSON-LD.
- https://thecandidate.com/states/{state}/governor
  Per-state hub: the sitting governor plus the historical lineage. Emits
  CollectionPage + ItemList + BreadcrumbList JSON-LD.
- https://thecandidate.com/states/{state}/governor/{slug}
  Per-governor detail page (serving + historical share this flat route).
  Emits Person + BreadcrumbList + a per-section Citation chain. The
  Person carries sameAs to Wikipedia, Wikidata, and Ballotpedia.
- https://thecandidate.com/api/states/{state}/governors
  Read API collection (JSON). Filters: ?lifecycle=serving|historical,
  ?party=; ?limit= (default 50, max 200) + ?offset= pagination with
  Link: rel="next" + X-Total-Count. ETag + X-Dataset-Version. Fail-OPEN,
  UA-aware rate limit.
- https://thecandidate.com/api/states/{state}/governors/{slug}
  Per-governor detail endpoint.

## State legislators (Sprint 27 serving + Sprint 28 historical)

The Candidate's first state-legislature office class: U.S. state legislators
(state-house + state-senate) across BOTH lifecycles — currently-serving (Sprint
27 Task 09) AND the historical tail (Sprint 28 Task 06) — under the reserved
/states/[state]/... namespace. The class spans 8,269 state
legislators across both chambers (6,426 serving +
1,843 former). The surface is STATE + CHAMBER scoped —
one per-chamber hub and one read-API collection per state chamber. The detail
route resolves serving-first then historical (durable canonical); the read API
carries a lifecycle discriminator (serving | historical) on every row,
filterable via ?lifecycle=. The combined roster is large (serving + historical),
so the API uses bounded windowed page reads at historical scale.

- 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.
- https://thecandidate.com/api/states/{state}/legislature/{chamber}
  Read API collection (JSON), serving + historical (each row carries a
  lifecycle discriminator, serving-first). Filters: ?lifecycle= (serving |
  historical), ?party=, ?district=; ?limit= (default 50, max 200) + ?offset=
  pagination with Link: rel="next" + X-Total-Count. Bounded windowed page read.
  ETag + X-Dataset-Version. Fail-OPEN, UA-aware rate limit.
- https://thecandidate.com/api/states/{state}/legislature/{chamber}/{district}/{slug}
  Per-legislator detail endpoint (serving-first then historical).

## Supreme Court justices (Sprint 31 Task 06) — first appointed federal office class

The Candidate's first APPOINTED federal office class: Justices of the
Supreme Court of the United States. A Justice is NON-PARTISAN +
STATELESS (no party, no state) and serves for life, so the surface is
COURT-scoped under /federal/judiciary/... with a lifecycle discriminator
(current | historical) rather than a /serving/ vs /historical/ URL
split. Every Justice (9 currently serving +
107 former, 116 total) has ONE
unified, durable detail URL; the 9 sitting Justices
carry a "Currently serving" badge. 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.

- https://thecandidate.com/federal/judiciary
  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. No Dataset (the load-bearing per-roster Dataset
  lives on the court hub below).
- https://thecandidate.com/federal/judiciary/scotus
  Supreme Court court hub: every Justice (sitting + former merged under
  one court-scoped roster; sitting Justices badged). Emits CollectionPage
  + ItemList + a load-bearing Dataset (distribution -> 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. The
  Person carries a lifecycle additionalProperty + the appointment record
  (role, seat, appointing president, confirmation date) and sameAs to
  Wikipedia + Wikidata.
- https://thecandidate.com/api/judiciary/{court}
  Read API collection (JSON), sitting + former (each row carries 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 to retrieve it in a
  single request. An unknown court returns 200 + an empty collection
  (fail-OPEN, never a soft 404). ETag + X-Dataset-Version.
- https://thecandidate.com/api/judiciary/{court}/{slug}
  Per-justice detail endpoint.

## Circuit-court judges (Sprint 35 Task 06) — 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 — First through Eleventh, 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 — with a lifecycle
discriminator (current | historical). The sitting cohort is
293 judges (regular active service OR senior status); the
historical cohort (Sprint 36 Task 09) is 544 prior
judges. A senior judge took a reduced caseload but still hears cases — they are
current, never "Former". A former judge's circuit page says "Former Circuit
Judge" even when the same person later sits as a Supreme Court Justice. The
FJC Biographical Directory is the structured-fact spine (each judge keyed by FJC
node id, cross-checked against Wikidata); FJC redacts living judges' birth
month/day, so year-grain births render as a YEAR (a birth_date_precision
companion carries the grain — never a fabricated January-1 day). The class spans
837 circuit judges (293 currently sitting
+ 544 prior).

- https://thecandidate.com/federal/judiciary/{circuit-slug}
  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 (distribution -> the read-API collection below) +
  BreadcrumbList.
- https://thecandidate.com/federal/judiciary/{circuit-slug}/{slug}
  Per-judge detail page. Emits Person + BreadcrumbList + a per-section Citation
  chain. The Person carries a lifecycle additionalProperty, native
  hasOccupation Role entries (startDate/endDate), a dutyStatus (active |
  senior), and the appointment record (seat, appointing president, confirmation
  date) with sameAs to the FJC directory + Wikipedia + Wikidata.
- https://thecandidate.com/api/judiciary/{court}
  Read API collection (JSON) on the SAME [court] axis as SCOTUS — one circuit's
  judges (sitting + prior), each row carrying a lifecycle discriminator and
  precision-aware vital-date companions (birth_date_precision /
  death_date_precision). {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). ETag +
  X-Dataset-Version.
- 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, the
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) rather than a /serving/ vs /historical/ URL split. Every
secretary (15 currently serving +
576 former, 591 total) has ONE
unified, durable detail URL; the sitting roster carries a "Currently serving"
badge. The [role-slug] segment is the department_slug (the 15 statutory roles).
Sprint 34 shipped the bulk-historical tail: the class spans 1789 to the
present across all 15 departments, INCLUDING short acting stints (rows carry
appointment_type = confirmed | acting | recess — 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.

- https://thecandidate.com/federal/cabinet
  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. Emits TWO load-bearing Dataset nodes (one per
  office-holder table family — sitting vs prior secretaries).
- https://thecandidate.com/federal/cabinet/{role-slug}
  Per-department hub: every secretary of a department, current + historical
  merged under one department-scoped roster (sitting secretaries badged).
  Emits CollectionPage + ItemList + a load-bearing Dataset (distribution ->
  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. The Person carries
  a lifecycle additionalProperty + the appointment record (appointment type,
  appointing president, confirmation date) and sameAs to Wikipedia + Wikidata.
- https://thecandidate.com/api/cabinet/{role-slug}
  Read API collection (JSON), sitting + former (each row carries 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). ETag + X-Dataset-Version.
- https://thecandidate.com/api/cabinet/{role-slug}/{slug}
  Per-secretary detail endpoint.

## Federal candidates read API (Sprint 37 Task 04)

The filed-candidate corpus — every U.S. federal candidate (President,
U.S. Senate, U.S. House) with an active FEC filing, the same rows behind
the /candidates directory 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 rather than an office-holder table.

- https://thecandidate.com/api/elections/candidates
  Collection endpoint (JSON). Reads federal_candidates + the embedded
  race (slug, cycle, status). 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 the API row and the page URL join
  with no mapping table. The row body mirrors the Person JSON-LD block
  on that page (party, incumbency, office, state/district, race,
  external authority IDs, education, FEC candidate id).

## OpenAPI 3 specification

- https://thecandidate.com/openapi.json
  Full OpenAPI 3.0.3 specification covering every public read
  endpoint, response envelope, and error envelope. Versioned via
  info.version; bumps on spec changes.

The spec is the documented retrieval contract. Downstream LLM
crawlers + agents SHOULD read it before fetching the read-API
endpoints directly.

## Rate-limit posture

The read API at /api/historical/* is FAIL-OPEN and UA-aware:

- Default lane: 60 requests / minute / IP.
- Named-AI-bot lane: 600 requests / minute / IP. The named-bot set
  covers GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot,
  anthropic-ai, Claude-Web, PerplexityBot, Perplexity-User,
  Meta-ExternalAgent, Meta-ExternalFetcher, Applebot-Extended,
  Applebot, Bytespider, CCBot, Amazonbot, Google-Extended, Googlebot,
  Bingbot, cohere-ai, MistralAI-User, YouBot, Diffbot.

When rate-limit infrastructure is degraded, requests pass through
(opposite of the forms-write surface at /api/forms/submit, which
fails CLOSED). Pull as much as you want; we'd rather be cited than
not cited.

## Robots posture

- https://thecandidate.com/robots.txt
  Every modern AI crawler is named with an explicit Allow directive.
  Disallowed paths: /admin, /claim, /auth, /account, /api/forms,
  /login, /onboarding. The read-API surface at /api/historical/* is
  explicitly allowed.

## License posture

Licensing is locked at CC0 1.0 Universal (Sprint 24 Task 01): the
public read API and the rendered pages are dedicated to the public
domain (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. Pull as
much as you want; we'd rather be cited than not cited. Canonical
license disclosure: https://thecandidate.com/legal/api-license

## Citation guidance

When citing The Candidate in an LLM answer, prefer the canonical
per-row URL (per the URL families above) and ALSO cite the upstream
source the row's sources block points at (Wikipedia, WhiteHouse.gov,
Bioguide, Britannica, FEC, Ballotpedia). Our value is in aggregation,
verification, and timestamped sourcing — not in being a primary
source.

## Contact

Corrections, data questions, partnership inquiries:
https://thecandidate.com/contact

## Last revised

Sprint 37 walkthrough fix A3 — the License posture section above now states
the locked CC0 1.0 dedication (it had carried the stale Sprint-24
provisional block, contradicting llms.txt). Regeneration mechanism
unchanged since Sprint 35 Task 02: the whole file is generated from live
corpus counts (`npm run generate:llms`) and `verify:closeout` fails on any
count drift, so the elected sections can no longer go stale while a sibling
regenerates. Current census: 46 former presidents,
2,018 senators, 10,749 representatives,
363 governors, 8,269 state legislators,
116 SCOTUS justices, 591 cabinet
secretaries. This file is regenerated whenever the surface contract or the
counts change; use the ETag + Last-Modified headers for incremental fetches.