# OppScore API

> Nonpartisan scores, roster and contact data for United States politicians.

Nonpartisan ratings, the full roster of United States politicians, contested
races with their candidate fields, contact channels, and the published scoring
instrument behind every number. Read-only. Every route is a GET and every
response is JSON, or CSV with `?format=csv`.

Base URL: https://oppscore.org/api
Auth: `Authorization: Bearer opp_...` or `X-API-Key: opp_...` (equivalent)
Get a key: https://oppscore.org/api/keys (free tier, no card)

## Docs

- [Full API reference](https://oppscore.org/api/v1/llms-full.txt): every route, parameter, response
  shape and example in one file. Fetch this if you are implementing against the API.
- [OpenAPI 3.1 document](https://oppscore.org/api/v1/openapi.json): the machine contract, for client
  generators and API explorers. Answers without a key.
- [Human documentation](https://oppscore.org/api): the same material as a web page.

## Plans

| plan | price | quota | rate | scores | contacts |
|---|---|---|---|---|---|
| free | $0 | 1,000/mo | 30/min | no | none |
| developer | $49/mo | 25,000/mo | 60/min | yes | official |
| campaign | $199/mo | 100,000/mo | 120/min | yes | official + campaign |
| newsroom | $499/mo | 250,000/mo | 240/min | yes | official + campaign |

Free needs no card. It carries the roster, the contested races, the election
dates and the entire scoring instrument. What it does not carry is the scores
themselves and the contact database.

## Routes

- `GET /v1/dirt-alerts` Recent accountability findings
- `GET /v1/elections/{state}` Races in a state
- `GET /v1/export/contacts` Bulk contact export
- `GET /v1/export/politicians` Bulk roster export
- `GET /v1/export/scores` Bulk scorecard export, one row per criterion
- `GET /v1/llms-full.txt` The entire API reference in one plain text file
- `GET /v1/llms.txt` Short documentation index for AI agents
- `GET /v1/me` Your key, plan and remaining quota
- `GET /v1/openapi.json` This document
- `GET /v1/politicians` List and filter the roster
- `GET /v1/politicians/{slug}` One politician in full
- `GET /v1/politicians/{slug}/contacts` Contact channels for one politician
- `GET /v1/politicians/{slug}/dirt-alerts` Accountability findings for one politician
- `GET /v1/politicians/{slug}/scorecard` Why this politician scores what they score
- `GET /v1/polls` Recent community polls
- `GET /v1/questions` The scoring instrument
- `GET /v1/races` Contested seats and their candidate fields
- `GET /v1/scores/{slug}/history` Every OppScore snapshot for one politician
- `GET /v1/states` States, with how many politicians and candidates each holds

## Start here

```bash
curl -H "Authorization: Bearer opp_your_key" "https://oppscore.org/api/v1/me"
```

`/v1/me` reports your plan, your quota and what you are entitled to. It is free
on every plan and does not consume quota, so it is the correct first call and a
safe health check.