API Documentation

Programmatic access to the VoteROI.com Mood Forecast model. Available on Enterprise tier. All endpoints return JSON; all timestamps are ISO 8601 UTC.

Authentication

API access uses bearer tokens issued from your account billing page. Send the token as a header:

Authorization: Bearer YOUR_API_KEY

Keys are scoped to your organization, rate-limited per the table below, and rotatable from the dashboard. Treat keys as secrets; commit them to environment variables, not source.

Rate limits

Responses include X-RateLimit-Remaining and X-RateLimit-Reset. 429 responses include a Retry-After header.

Endpoints

GET /api/forecast

The full forecast snapshot: national mood index, top-5 presidential 2028, and senate / governor 2026 race probabilities.

curl -H "Authorization: Bearer $KEY" https://sentiment.voteroi.com/api/forecast

GET /api/race/:race_id

Race-level deep dive: P(D), confidence interval, dimension contributions, candidate fit, model version.

curl -H "Authorization: Bearer $KEY" https://sentiment.voteroi.com/api/race/senate-2026-NC

GET /api/national-index

Daily national mood index time series for the last 365 days.

GET /api/state/:state

State composite score, dimension breakdown, and top drivers. Two-letter state code.

GET /api/brier

Current model Brier score by cycle and by office, plus model_version metadata.

Examples

Python

import requests
r = requests.get(
    "https://sentiment.voteroi.com/api/race/senate-2026-NC",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(r.json()["p_dem"], r.json()["ci_pct"])

JavaScript (Node)

const res = await fetch("https://sentiment.voteroi.com/api/race/senate-2026-NC", {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const race = await res.json();
console.log(race.p_dem, race.ci_pct);

Errors

Changelog and stability

API responses are versioned implicitly by the model_version field; we will not remove or rename fields without a 90-day deprecation notice. New fields may be added at any time. See /changelog for model version history.