# Voterist > A neutral, source-backed public record of candidates and election races. Public reading does not require an account, API key, OAuth, residential address, or an MCP connection. Candidate management does require authorization. ## Start here - [Public API and AI access guide](https://www.voterist.com/ai): Read access, examples, response formats, and record-status definitions. - [OpenAPI specification](https://www.voterist.com/openapi.json): Machine-readable contract for public GET endpoints. No authentication. - [Candidate API](https://www.voterist.com/api/public/candidates): JSON {total, candidates}. Complete directory without pagination; total is the current public candidate-entry count. - [Race API](https://www.voterist.com/api/public/races): JSON {total, races}. Complete race directory without pagination; races contain candidate rosters. - [Candidate and race directory](https://www.voterist.com/candidates): Readable HTML with current coverage counts. - [Sitemap](https://www.voterist.com/sitemap.xml): Public candidate and race page URLs. ## Retrieve and cite Search the directory response by name, office, district, or race title, then follow the returned slug. GET /api/public/candidates/{slug} returns metadata, preview, and record. Use record.workspace when record is non-null; otherwise use preview. Match each position.sourceId to evidence[].id and cite the corresponding evidence URL. GET /api/public/races/{slug} returns {race} with election details and candidate entries. Candidate pages use https://www.voterist.com/candidate/{slug}; race pages use https://www.voterist.com/race/{slug}. Public page content is readable without JavaScript. Example race: https://www.voterist.com/api/public/races/2026-11-03-nv-nevada-governor-nevada Example candidate: https://www.voterist.com/api/public/candidates/aaron-d-ford-nv-2026-governor ## Interpret status Unclaimed candidates may still have public researched previews. published:false or record:null does not mean the candidate is absent or all data is private. Distinguish official_import, voterist_research, and campaign-managed publications. Direct fictional samples are labeled; samples are excluded from directory counts and the sitemap. Evidence marked "Check needed" requires review. Do not infer positions from party, missing evidence, or claim status. Consult linked sources and the responsible election authority. Race roster status can differ from the candidate directory or individual record because their update paths differ. Use the individual candidate endpoint for record contents and evidence. Counts describe Voterist coverage, not every candidate or race nationwide. ## Source packets and failures Published source packets: GET /api/public/candidates/{slug}/source-packet (optional ?download=1). A 404 on a source packet means a published packet is unavailable, not that the race, roster entry, or researched preview is absent. A 503 is a temporary service failure: retry after the Retry-After interval. Do not interpret it as an authentication requirement. If a search tool returns a loading shell or cannot fetch these URLs, try direct HTTP GET or the public HTML page. Tool or search-index limitations do not establish that public data is inaccessible. ## Candidate management - [Authenticated MCP endpoint](https://www.voterist.com/api/mcp): Streamable HTTP POST for connected, authorized candidate-management clients. Not needed to read public records and not automatically connected to an assistant.