officials

Representation lookup for a US ZIP code: both U.S. Senators, the U.S. House member for that ZIP's congressional district, and the state's statewide executives (governor, attorney general, and similar). Every official carries source_url (the capture origin) and source_link (a public page).

{
  "type": "object",
  "properties": {
    "zip": {
      "type": "string",
      "description": "5-digit US ZIP code, e.g. 04101"
    }
  },
  "required": [
    "zip"
  ]
}

Search for politicians and elected officials across all levels of US government — federal, state, county, municipal. Filter by name, state, party, level, chamber, or office title. Returns officials with their current office, party, and contact info.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Official name (partial match, e.g. \"Sanders\" or \"Alexandria\")"
    },
    "state": {
      "type": "string",
      "description": "State abbreviation (e.g. FL, NY, CA)"
    },
    "party": {
      "type": "string",
      "description": "Party name (e.g. Democrat, Republican, Independent)"
    },
    "level": {
      "type": "string",
      "enum": [
        "federal",
        "state",
        "county",
        "municipal",
        "school"
      ],
      "description": "Government level"
    },
    "chamber": {
      "type": "string",
      "enum": [
        "senate",
        "house",
        "council",
        "board"
      ],
      "description": "Legislative chamber"
    },
    "office": {
      "type": "string",
      "description": "Office title (e.g. Senator, Mayor, Governor, Town Clerk)"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "candidate",
        "former",
        "defeated"
      ],
      "description": "Status (default: active + candidate)"
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 50)",
      "default": 50
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset",
      "default": 0
    }
  }
}

Get full details for a specific official by ID — biography, party, office, policy positions, committee assignments, campaign finance, social media, and contact info. All data includes source URLs for verification.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Official ID from politics_search results"
    },
    "bioguide_id": {
      "type": "string",
      "description": "Congress.gov Bioguide ID (e.g. S000033 for Bernie Sanders)"
    },
    "positions_limit": {
      "type": "integer",
      "description": "Max policy positions to return (default 15, max 250). Response is bounded so it fits any AI client tool-result limit."
    },
    "positions_offset": {
      "type": "integer",
      "description": "Pagination offset for positions (page with offset += limit)."
    },
    "expand": {
      "type": "boolean",
      "description": "Return the fuller record (larger response, untruncated detail). Default false = bounded for AI consumption."
    }
  }
}

Resolve a messy name string (e.g. "Rep. Johnson", "cornyn") to a canonical official — returns the best match with a 0-1 confidence score and ranked alternatives. Use this first when you have a name but not an ID; then call politics_official with best.id. Add state to disambiguate.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name to resolve (partial/with title/lowercase all OK)"
    },
    "state": {
      "type": "string",
      "description": "State abbreviation to disambiguate (e.g. TX)"
    },
    "level": {
      "type": "string",
      "description": "Government level to disambiguate",
      "enum": [
        "federal",
        "state",
        "county",
        "municipal",
        "school"
      ]
    }
  },
  "required": [
    "name"
  ]
}

Get all current officials for a US state — federal senators and representatives, state legislators, and any indexed local officials. Organized by government level.

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "State abbreviation (e.g. FL, CA, TX)"
    }
  },
  "required": [
    "state"
  ]
}

Policy positions across officials by topic, covering who supports or opposes issues such as crypto, stablecoins, AI, healthcare, and guns. Each position carries a source URL and origin hash. Returns compact records by default (id, name, party, state, stance, summary, source) with a total count; the compact parameter controls row detail and offset controls paging.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Policy topic label — use exact stored labels: Cryptocurrency, Technology, Healthcare, Immigration, Climate, Gun Control, Abortion, Taxes, Economy, Education, National Security, Housing, Criminal Justice, Social Security, Voting Rights, Agriculture, Trade"
    },
    "state": {
      "type": "string",
      "description": "Filter by state (2-letter code)"
    },
    "party": {
      "type": "string",
      "description": "Filter by party (Republican, Democrat)"
    },
    "compact": {
      "type": "boolean",
      "default": true,
      "description": "Compact mode (default). Small bounded record per position; use with offset to page. Set false for full rows (limit capped at 50)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "description": "Pagination offset. Response includes total; page by offset += limit."
    },
    "limit": {
      "type": "integer",
      "default": 100,
      "description": "Max results per page. Compact: default 100, max 250. Full: default 25, max 50."
    }
  },
  "required": [
    "topic"
  ]
}

Get summary statistics for the politics.rootz.global database — total officials, breakdown by level, party, state, and chamber. Shows coverage completeness.

{
  "type": "object",
  "properties": {}
}

Get the full origin timeline for a politician — every page snapshot, every position change, every data source with hash proof. The political wayback machine. Shows what changed, when, and where the data came from.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Official ID"
    },
    "limit": {
      "type": "integer",
      "default": 100
    }
  },
  "required": [
    "id"
  ]
}

Get recent changes detected across all politicians — position shifts, website updates, new data. Each change links to the before/after snapshots with origin proof.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50
    },
    "since": {
      "type": "string",
      "description": "ISO date to filter changes after (e.g. 2026-05-01)"
    }
  }
}

Get origin archive statistics — total snapshots, changes detected, origin proofs recorded, unique URLs tracked. Shows the depth of the political wayback machine.

{
  "type": "object",
  "properties": {}
}

Create a citizen bridge page — a personalized workspace for tracking representatives, comparing positions, and taking action (write letters, log calls). Returns a shareable URL that any AI agent can collaborate on. Optionally auto-populates with the citizen's state representatives.

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "State abbreviation — auto-adds federal representatives"
    },
    "zip": {
      "type": "string",
      "description": "ZIP code for precise district matching"
    },
    "topics": {
      "type": "string",
      "description": "Comma-separated topics of interest (e.g. Healthcare,Climate)"
    }
  }
}

Current state of a citizen bridge workspace: tracked officials, saved comparisons, drafted actions, and messages.

{
  "type": "object",
  "properties": {
    "hash": {
      "type": "string",
      "description": "Bridge page session hash"
    },
    "agent_id": {
      "type": "string",
      "description": "Your agent identifier for multi-agent tracking"
    }
  },
  "required": [
    "hash"
  ]
}

Compare multiple politicians side-by-side on a bridge page — positions, party, office, campaign finance. Optionally filter to a specific topic.

{
  "type": "object",
  "properties": {
    "hash": {
      "type": "string",
      "description": "Bridge page session hash"
    },
    "official_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Array of official IDs to compare"
    },
    "topic": {
      "type": "string",
      "description": "Optional topic to focus comparison on"
    },
    "title": {
      "type": "string",
      "description": "Title for this comparison"
    }
  },
  "required": [
    "hash",
    "official_ids"
  ]
}

Draft a letter to a politician on the citizen's bridge page. The letter gets an origin hash for proof of content. Returns delivery options (email, web form, USPS, phone).

{
  "type": "object",
  "properties": {
    "hash": {
      "type": "string",
      "description": "Bridge page session hash"
    },
    "official_id": {
      "type": "integer",
      "description": "Official to write to"
    },
    "subject": {
      "type": "string",
      "description": "Letter subject"
    },
    "body": {
      "type": "string",
      "description": "Letter body text"
    },
    "action_type": {
      "type": "string",
      "enum": [
        "letter",
        "email",
        "call",
        "meeting"
      ],
      "default": "letter"
    }
  },
  "required": [
    "hash",
    "official_id",
    "body"
  ]
}

Details of a US bill or resolution: vote breakdown, sponsors, cosponsors, status, and origin proof. Returns metadata, a short text excerpt, and a text index by default; full legislative text is omitted because omnibus bills exceed typical token caps. The include_text parameter controls whether the complete text is returned in a single response.

{
  "type": "object",
  "properties": {
    "bill_id": {
      "type": "string",
      "description": "Bill ID (e.g. hr3424-119 for House bill 3424 in 119th Congress)"
    },
    "include_text": {
      "type": "string",
      "enum": [
        "none",
        "excerpt",
        "full"
      ],
      "default": "excerpt",
      "description": "excerpt (default): metadata + ~1.2KB head + text index. none: metadata + index only. full: entire full_text (may exceed the token cap for large bills)."
    }
  },
  "required": [
    "bill_id"
  ]
}

Section index for a bill: every "SEC. N" heading with its character offset and length, plus the whole-bill origin hash (content_hash) and total text length. A small response that describes the structure of a large bill.

{
  "type": "object",
  "properties": {
    "bill_id": {
      "type": "string",
      "description": "Bill ID (e.g. hr7148-119)"
    }
  },
  "required": [
    "bill_id"
  ]
}

One signed, bounded slice of a bill's full legislative text, addressed by part number or section label. Each response carries part and total_parts, next_part, the slice's part_sha256, and the whole-bill content_hash. Parts 1 through total_parts concatenated in order hash to content_hash, so a bill too large to return in a single response remains verifiable as complete and unaltered.

{
  "type": "object",
  "properties": {
    "bill_id": {
      "type": "string",
      "description": "Bill ID (e.g. hr7148-119)"
    },
    "part": {
      "type": "integer",
      "default": 1,
      "description": "1-based part number. Response tells you total_parts and next_part."
    },
    "section": {
      "type": "string",
      "description": "Jump to a section by label instead of part, e.g. \"2\", \"SEC. 2\", or \"preamble\". Overrides part."
    },
    "max_chars": {
      "type": "integer",
      "default": 30000,
      "description": "Max characters per part (2000–60000). Larger = fewer parts but bigger responses."
    }
  },
  "required": [
    "bill_id"
  ]
}

Search bills by topic, sponsor, status, or congress. Returns bill metadata and whether full text is available.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Topic keyword (e.g. crypto, defense, healthcare)"
    },
    "sponsor": {
      "type": "string",
      "description": "Sponsor name or bioguide ID"
    },
    "congress": {
      "type": "integer",
      "description": "Congress number (119 = 2025-2026)",
      "default": 119
    },
    "status": {
      "type": "string",
      "description": "Bill status: introduced, committee, passed_house, passed_senate, enacted"
    },
    "limit": {
      "type": "integer",
      "default": 20
    }
  }
}

Get a candidate's Campaign Data Standard (CDS) feed: a single machine-readable record of who they are, the offices they hold and seek, their positions in their own words (each source-linked), their voting record by reference, and declared data gaps. This is the standardized, signed feed an AI or reporter uses to grab a candidate's positions and verify they are genuine. Every MCP response is signed; the standalone signed feed is also at /official/{id}/candidate.json. Tier is "rootz-compiled" until the campaign claims and signs it ("candidate-signed").

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Official ID (from politics_search)"
    },
    "bioguide_id": {
      "type": "string",
      "description": "Bioguide ID (alternative to id)"
    },
    "positions_limit": {
      "type": "integer",
      "description": "Max positions in the delivered feed (default 15, max 500). The complete signed feed (all positions) is always at signed_feed_url."
    },
    "positions_offset": {
      "type": "integer",
      "description": "Pagination offset for positions."
    },
    "expand": {
      "type": "boolean",
      "description": "Deliver more positions inline (larger response). Default false = bounded for AI consumption."
    }
  }
}

Compare an official's stated positions against their actual roll-call votes, per topic — what they SAY vs how they VOTED, both source-linked. Does NOT label agreement/contradiction (you judge and cite); surfaces the juxtaposition no unsigned source can. Use official id.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Official ID"
    }
  },
  "required": [
    "id"
  ]
}

Coverage map: per-state, per-dataset completeness (officials by level, positions, finance, state-legislative votes). Shows WHERE the data is deep (federal — complete) vs sparse (local). Use it to know whether silence means "no data captured" rather than "nothing there".

{
  "type": "object",
  "properties": {}
}

Get the full transparency methodology — how we collect, assess, extract, sign, and verify political data. Includes quality assessment algorithm (signals + weights), trust levels, data sources, cron schedule, and what we can and cannot prove. Open and auditable.

{
  "type": "object",
  "properties": {}
}

Get the complete origin proof chain for an official — every data source, content hash, quality assessment, snapshot history, and verification instructions. Proves where every piece of data came from.

{
  "type": "object",
  "properties": {
    "official_id": {
      "type": "integer",
      "description": "Official ID"
    }
  },
  "required": [
    "official_id"
  ]
}

Search Congressional Record floor speeches by official, topic, date range, or keyword. Returns verbatim text from the official government record with origin proof hash. Every speech is directly citable with a GPO source URL.

{
  "type": "object",
  "properties": {
    "bioguide_id": {
      "type": "string",
      "description": "Bioguide ID (e.g. L000571 for Lummis, S001184 for Tim Scott)"
    },
    "official_id": {
      "type": "integer",
      "description": "Official ID from politics_search"
    },
    "topic": {
      "type": "string",
      "description": "Topic (Cryptocurrency, Healthcare, Immigration, etc.)"
    },
    "date_from": {
      "type": "string",
      "description": "Start date ISO (e.g. 2025-01-03)"
    },
    "date_to": {
      "type": "string",
      "description": "End date ISO"
    },
    "chamber": {
      "type": "string",
      "enum": [
        "house",
        "senate"
      ],
      "description": "Filter by chamber"
    },
    "text": {
      "type": "string",
      "description": "Full-text search within speech content"
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "description": "Max results"
    }
  }
}

Registered federal candidates for the 2026 election cycle, filterable by state, office (senate, house, president), party, or presence of a campaign URL. Returns campaign website, social media links, FEC data, and position and speech counts.

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Two-letter state code (e.g. ME, CA, TX)"
    },
    "office": {
      "type": "string",
      "enum": [
        "senate",
        "house",
        "president"
      ],
      "description": "Filter by office"
    },
    "party": {
      "type": "string",
      "description": "Filter by party (Democrat, Republican, Libertarian, etc.)"
    },
    "has_url": {
      "type": "boolean",
      "description": "Only return candidates with campaign websites"
    },
    "limit": {
      "type": "integer",
      "default": 50,
      "description": "Max results (default 50)"
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "description": "Pagination offset"
    }
  }
}

Search state legislature votes across 26+ US states. Filter by state, topic, or date. Returns bill title, vote result, yes/no counts.

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Two-letter state code (CA, TX, NY, etc.)"
    },
    "topic": {
      "type": "string",
      "description": "Topic filter (Healthcare, Economy, Education, etc.)"
    },
    "days": {
      "type": "integer",
      "description": "Look back N days (default 30, max 365)",
      "default": 30
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 30, max 100)",
      "default": 30
    },
    "bill_id": {
      "type": "string",
      "description": "Specific bill identifier (e.g. HB 1234)"
    }
  }
}

Search US municipalities (cities, towns, villages, counties). Every incorporated place in the US with coordinates. Filter by state, name, or type. Returns website, platform, meeting calendar, and board/commission info where available.

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Two-letter state code (MA, CA, TX, etc.)"
    },
    "name": {
      "type": "string",
      "description": "Municipality name (partial match)"
    },
    "type": {
      "type": "string",
      "description": "Place type: city, town, village, borough, county, cdp",
      "enum": [
        "city",
        "town",
        "village",
        "borough",
        "county",
        "cdp",
        "place",
        "charter_township"
      ]
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 30)",
      "default": 30
    }
  }
}

Creates a Just the Facts watchlist bound to an email address, covering any combination of specific officials, issue topics, and a town with state for local meetings, agendas, and minutes. Sends a double-opt-in confirmation email and returns the bridge workspace URL.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Subscriber email (required)"
    },
    "name": {
      "type": "string",
      "description": "Watchlist name"
    },
    "officials": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Official IDs to track"
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issue topics (e.g. Crypto, Healthcare)"
    },
    "town": {
      "type": "string",
      "description": "Town/city to track local meetings (e.g. Fort Myers)"
    },
    "state": {
      "type": "string",
      "description": "2-letter state for the town"
    },
    "cadence": {
      "type": "string",
      "enum": [
        "daily",
        "weekly"
      ],
      "description": "Digest frequency"
    },
    "report_prompt": {
      "type": "string",
      "description": "Plain-English brief for how the digest is written"
    }
  },
  "required": [
    "email"
  ]
}

Search the SIGNED public-poll archive. Unlike aggregators, every poll keeps the EXACT question wording, population base (LV/RV/adults), sample size, margin of error, mode, and per-option toplines — first-party sourced, snapshot-hashed, and cryptographically signed (verifiable). Filter by race_key, state, subject (e.g. "approval", "Senate"), pollster, or since (ISO date). Returns a list; call politics_poll {id} for full detail + signature. Use this when a question hinges on what a poll ACTUALLY asked vs how it was reported.

{
  "type": "object",
  "properties": {
    "race_key": {
      "type": "string",
      "description": "Stable contest key to get every poll of one race over time (e.g. us-pres-approval-trump)"
    },
    "state": {
      "type": "string",
      "description": "2-letter state (omit for national)"
    },
    "subject": {
      "type": "string",
      "description": "Subject substring (e.g. \"approval\", \"TX Senate\", \"immigration\")"
    },
    "pollster": {
      "type": "string",
      "description": "Pollster substring (e.g. \"Quinnipiac\", \"Emerson\")"
    },
    "since": {
      "type": "string",
      "description": "Only polls whose field_end >= this ISO date (e.g. 2026-08-01)"
    },
    "cycle": {
      "type": "integer",
      "description": "Election/survey cycle year (e.g. 2026)"
    },
    "limit": {
      "type": "integer",
      "default": 50
    },
    "offset": {
      "type": "integer",
      "default": 0
    }
  }
}

Get one poll in full: pollster, sponsor, field dates, population, sample size, margin of error, mode, the VERBATIM question(s) asked, per-option toplines, the first-party source_url, and the signature (poll_proof) that binds the exact wording and numbers. This is the ground truth to check any claim about a poll against.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Poll ID from politics_polls results"
    }
  },
  "required": [
    "id"
  ]
}