API Reference

Base URL: https://poltrapro.com/api/v1 · Version: 1

Authentication

All requests require an API key passed as a Bearer token in the Authorization header. Get a free key at poltrapro.com/developers.

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/candidates"

Keep your API key secret. Do not expose it in client-side code or public repositories. If compromised, contact PolTraPro@proton.me to reset it.

Rate Limits

Rate limits are enforced per API key per calendar day (UTC). Exceeding the limit returns a 429 response. Limits reset at midnight UTC.

Tier	Requests / day	Price
`free`	100	Free
`hobby`	1,000	$29/mo
`pro`	10,000	$99/mo
`enterprise`	Unlimited	Contact us

Errors

All errors return JSON with an error field describing the problem.

Status	Meaning
`401`	Missing, malformed, or invalid API key
`404`	Candidate not found. Use /candidates to search.
`429`	Rate limit exceeded for your tier
`500`	Server error — try again shortly

GET /candidates

Search and filter tracked candidates. Returns lightweight summaries with a profileUrl for fetching full data.

GET /api/v1/candidates
Authorization: Bearer ptpk_live_YOUR_KEY

Query parameters

state

string

Two-letter state code. Example: FL, TX, NY

office

string

Partial match. Example: Senate, House, Governor

party

string

Republican, Democrat, or Independent

level

string

federal or state

q

string

Name search — partial match

limit

integer

Max results. Default 50, max 200

offset

integer

Pagination offset. Default 0

Example

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/candidates?state=FL&office=Senate"

{
  "data": [
    {
      "id": "ashley-moody",
      "name": "Ashley Moody",
      "party": "Republican",
      "office": "U.S. Senate",
      "state": "FL",
      "level": "federal",
      "fecId": "S6FL00640",
      "congressBioId": "M001244",
      "profileUrl": "/api/v1/candidate/ashley-moody/profile",
      "publicUrl": "https://poltrapro.com/candidate/ashley-moody"
    }
  ],
  "total": 1,
  "pagination": { "limit": 50, "offset": 0, "hasMore": false }
}

GET /candidate/:id/profile

The core joined endpoint. Returns all available data for a candidate in a single response — finance, legislation, outside spending, and prediction market odds pre-joined server-side.

GET /api/v1/candidate/:id/profile
Authorization: Bearer ptpk_live_YOUR_KEY

Path parameters

idrequired

string

Candidate slug from /candidates. Example: ashley-moody, jon-ossoff

Response fields

finance.totalRaised

number

Total campaign receipts in the current cycle (FEC)

finance.burnRate

number

Percent of raised funds spent. Derived: totalSpent/totalRaised × 100

finance.pacShare

number

Percent of funds from PACs. Derived: pacContributions/totalRaised × 100

legislation.sponsored

array

Bills sponsored by this candidate. Includes CRS summaries where available.

outsideSpending

object

FEC Schedule E data: totalFor, totalAgainst, netImpact, topCommittees

markets.polymarket

array

Active Polymarket markets mentioning this candidate, sorted by relevance

trades

array

Congressional stock trades. Empty — data pipeline in development.

revolvingDoor

array

Lobbying transitions. For the full set, use GET /revolving-door?candidate=<slug>.

_meta.tier

string

Your API key's tier at time of request

Example

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/candidate/ashley-moody/profile"

{
  "id": "ashley-moody",
  "name": "Ashley Moody",
  "party": "Republican",
  "finance": {
    "cycle": 2026,
    "totalRaised": 8407063,
    "totalSpent": 1277671,
    "cashOnHand": 7129392,
    "pacContributions": 1504500,
    "burnRate": 15,
    "pacShare": 18
  },
  "legislation": {
    "sponsored": [ { "billId": "S3747-119", "title": "Home School Graduation Recognition Act", ... } ],
    "sponsoredCount": 16
  },
  "outsideSpending": {
    "totalFor": 279283,
    "totalAgainst": 11675,
    "netImpact": 267608,
    "topCommittees": [ ... ]
  },
  "markets": {
    "polymarket": [
      { "question": "Will Ashley Moody be the Republican nominee?", "outcomePrices": [0.94, 0.06] }
    ]
  },
  "_meta": { "version": "1", "tier": "free" }
}

GET /revolving-door

Career transitions between U.S. government and the private sector — former staffers and officials who became lobbyists, advocacy operators, or corporate insiders. Sourced from sworn LDA filings (2 U.S.C. § 1606). Pre-joined: each row includes person, from-role, to-role, and the originating source documents.

The endpoint returns only confidence="confirmed" rows — direct documentary evidence from sworn filings. Lower-tier inferences (probable, unconfirmed) are never exposed via the public API.

GET /api/v1/revolving-door
Authorization: Bearer ptpk_live_YOUR_KEY

Query parameters

direction

string

min_score

integer

Minimum notability score (0–100). Default 0. See methodology for the scoring formula.

candidate

string

Candidate slug or uuid. Returns transitions for persons who held a role linked to this candidate.

person

string

Person uuid. Returns this person's transitions only.

org

string

Organization uuid. Returns transitions where the from-role OR to-role is at this organization.

limit

integer

Max results. Default 50, max 200.

offset

integer

Pagination offset. Default 0.

Example

curl -H "Authorization: Bearer ptpk_live_YOUR_KEY" \
  "https://poltrapro.com/api/v1/revolving-door?direction=gov_to_private&min_score=60&limit=2"

{
  "data": [
    {
      "id": "1f7e…",
      "direction": "gov_to_private",
      "gap_days": 92,
      "notability_score": 85,
      "flag_reasons": ["gov_to_private", "from_legislative", "senior_role", "fast_revolve"],
      "person": { "id": "8a2b…", "full_name": "Jane Doe" },
      "from_role": {
        "title": "Chief of Staff",
        "start_date": "2017",
        "end_date": "2023",
        "organization": { "id": "a3…", "name": "Office of Senator Smith", "type": "government_legislative" }
      },
      "to_role": {
        "title": "Lobbyist",
        "start_date": null,
        "end_date": null,
        "is_current": true,
        "organization": { "id": "b8…", "name": "Akin Gump", "type": "lobbying_firm" }
      },
      "sources": [
        { "url": "https://lda.gov/api/v1/filings/abc-123/", "source_type": "lda_filing", "content_hash": "9f4c…", "fetched_at": "2026-05-09T12:00:00Z" }
      ],
      "_links": {
        "person": "/api/v1/revolving-door?person=8a2b…",
        "from_org": "/api/v1/revolving-door?org=a3…",
        "to_org": "/api/v1/revolving-door?org=b8…",
        "public_person": "https://poltrapro.com/revolving-door/people/8a2b…",
        "public_from_org": "https://poltrapro.com/revolving-door/orgs/a3…",
        "public_to_org": "https://poltrapro.com/revolving-door/orgs/b8…"
      }
    }
  ],
  "total": 142,
  "pagination": { "limit": 2, "offset": 0, "hasMore": true },
  "_meta": { "version": "1", "tier": "pro", "confidence_floor": "confirmed" }
}

GET /money-vote-gap/* — withdrawn

Status: withdrawn 2026-05-28. All /api/money-vote-gap/* endpoints (per-candidate cells, leaderboard, stats ticker) return HTTP 410 Gone while the underlying classifier is restored.

Reason. A graded evaluation of the vote-tag classifier (n=100 federal roll-calls, deepseek-v4-pro grader, committed eval set scripts/eval-sets/votes-federal-100.json) scored 22% overall correct (Wilson 95% CI [15%, 31%]) — below the ≥85% publication gate this site holds itself to. Per that gate, the metric is withdrawn until restoration. Full findings: docs/audits/mvg-withdrawn-2026-05-28.md.

Current response shape

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "gone",
  "message": "The Money-Vote Gap API has been withdrawn pending classifier-accuracy restoration.",
  "withdrawn_at": "2026-05-28",
  "restoration_criteria": "Per-industry Wilson 95% lower bound ≥ 85% on n≥20 verdicts against the committed evaluation set scripts/eval-sets/votes-federal-100.json.",
  "audit_doc": "docs/audits/mvg-withdrawn-2026-05-28.md"
}

Restoration criteria

Per-industry Wilson 95% lower bound ≥ 85% on n≥20 verdicts against the committed eval set. Industries that clear the bar may be partially restored ahead of the full surface. We will publish a follow-up graded audit when restoration begins, with the same harness and grader so numbers are directly comparable.

Other PTP endpoints (candidates, profile, revolving-door) are unaffected.

← Back to developers PolTraPro@proton.me