Build on the 2026 elections data

Connect your own AI

SuperCitizen is also a remote MCP server, so the AI you already use can look things up here with sources. Public election tools work right away, with no account. The two tools that read your own account ask you to sign in the first time one is used, and you choose what the app can see. You can disconnect it any time from your profile.

https://supercitizen.org/mcp

• Claude (web, desktop and mobile): go to Customize → Connectors, choose Add custom connector, and paste the URL above.
• ChatGPT: with developer mode on, add a new connector with the URL above and choose OAuth when it asks how to sign in.
• Claude Code: run claude mcp add --transport http supercitizen https://supercitizen.org/mcp, then type /mcp in Claude Code to sign in when a tool needs your account.
• Scripts and headless agents: send an API key instead of signing in, as Authorization: Bearer sc_live_… (in Claude Code, --header). A key reads your account only if you gave it that scope.

Every tool is read-only and returns the same envelope as the API below, with its sources map. The server asks the AI to cite those sources and to stay neutral: no endorsements or ratings of candidates. Sign-in uses OAuth 2.1 with PKCE; apps identify themselves with a Client ID Metadata Document, so there is nothing to register. The discovery documents are at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. The same sign-in also works for the API’s /api/v1/me endpoints: request resource=https://supercitizen.org/api/v1.

Quick start

1. Sign in and create a key. Keys are free and look like sc_live_….
2. Send it with every request as Authorization: Bearer sc_live_… (or X-API-Key: sc_live_…).

curl -H "Authorization: Bearer $SUPERCITIZEN_KEY" \
  "https://supercitizen.org/api/v1/races?state=GA"

curl -H "Authorization: Bearer $SUPERCITIZEN_KEY" \
  "https://supercitizen.org/api/v1/candidates/<candidate-id>"

curl -X POST -H "Authorization: Bearer $SUPERCITIZEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"1100 Congress Ave, Austin, TX 78701"}' \
  "https://supercitizen.org/api/v1/lookup"

Endpoints

List endpoints take limit (1–500, default 100) and offset, and return a page object with the total. Full parameters and response shapes are in the OpenAPI 3.1 document.

Responses and sources

Every response is an envelope: data, a sources map, and meta. Facts point at sources by id (in fields named sources or sourceIds), and every id resolves in the sources map with its URL, publisher and retrieval date. Text we drafted with AI is marked in each candidate's origin field and is made of individually cited sentences.

{
  "data": {
    "id": "2026-ga-us-senate",
    "state": "GA",
    "office": "us-senate",
    "division": "ocd-division/country:us/state:ga",
    "title": "U.S. Senate · Georgia",
    "format": "majority-runoff",
    "candidates": [ { "id": "…", "name": "…", "partyLabels": ["…"], … } ],
    "sourceIds": ["ballot:GA:sos-cert"]
  },
  "sources": {
    "ballot:GA:sos-cert": {
      "url": "https://…",
      "title": "…",
      "publisher": "Georgia Secretary of State",
      "retrieved": "2026-10-27",
      "kind": "election-office"
    }
  },
  "meta": { "version": "1.0.0", "election": "2026-11-03", … }
}

IDs

• Races are cycle-qualified: 2026-tx-us-house-37, 2026-oh-us-senate-special, 2026-ga-governor. Each race also carries an Open Civic Data division id.
• Candidates are people, with durable slugs that will carry across future elections: jane-q-doe, or with a state added when two people share a name.
• Bills are type, number and Congress: hr1-119, s5-118, hjres7-118.
• Candidates also carry their fecCandidateId and, for members of Congress, their bioguideId, so you can join with other datasets.

Limits, errors and versions

• Each key gets 60 requests a minute and 10,000 a day, shared between the API and the MCP server (a connected app gets the same budget per person). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get 429 with Retry-After. Need more? Email [email protected].
• Errors look like { "error": { "code": "not_found", "message": "…" } } with a matching HTTP status: 400, 401, 403, 404, 422, 429 or 503.
• Versioning: the path carries the major version (/api/v1). Within v1 we only add fields and endpoints; anything that would break a client ships as v2, announced here first, with v1 kept running alongside it.
• Responses may be cached for five minutes (the /api/v1/me endpoints never are). Data changes when sources change — new FEC reports, corrections — and the corrections log records every fix.

Using the data

Facts come from public records — state election offices, the FEC, Congress — and candidates' own public statements. Summaries we wrote are licensed CC BY-SA 4.0. Please credit SuperCitizen and keep the links to original sources. If you build a voter guide, keep it nonpartisan in the same spirit: same rules for every candidate, no claims without sources.