REST API

Pundit Ledger API Reference

Integrate pundit accuracy scores, prediction history, and draft results into your app, betting tool, or agent.

https://pundit-ledger-api-wvhvx2muna-uc.a.run.app

Quick start

Get up and running in 2 minutes

Get an API key

Make your first call

Pass your key in the x-api-key header on every request.

Explore & build

Browse the endpoint reference below or use the interactive schema at /docs on the base URL.

bash

curl "https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/leaderboard?limit=5" \
  -H "x-api-key: capk_live_your_key"

Authentication

API key authentication

API-key enforcement is active on all data endpoints. Every request to /v1/* endpoints requires a valid x-api-key header. Keys are provisioned via your Cap Alpha dashboard and are validated against your account in real-time.

bash

# Pass your key in this header (required for all /v1/* endpoints)
x-api-key: capk_live_your_key

Never expose your API key in client-side code or public repositories. If a key is compromised, rotate it from your dashboard immediately.

Error response when key is missing or invalid:

json

HTTP 401
{ "detail": "Invalid or missing API key" }

Rate limits

Tiers & rate limits

API access scales with your subscription tier. The number of active keys and request throughput both increase as you upgrade.

Tier	Max active keys	Notes
free	1	Public leaderboard, limited history
pro	3	Full prediction history, multi-sport
api_starter	10	Suitable for small integrations
enterprise	25	High-volume, priority support

Rate-limited requests receive HTTP 429. Contact support@cap-alpha.co to upgrade.

Endpoints

Endpoint reference

GET/Service health check — no auth required

bash

curl https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/

json

{
  "status": "ok",
  "service": "pundit-prediction-ledger",
  "version": "1.0.0"
}

GET/v1/leaderboardPundits ranked by weighted accuracy score

Returns pundits ranked by weighted accuracy (accuracy × timeliness). Results are cached for 5 minutes.

Name	Type	Required	Description	Example
limit	integer	no	Number of pundits to return (1–100, default 25)	?limit=10

bash

curl "https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/leaderboard?limit=10" \
  -H "x-api-key: capk_live_your_key"

json

{
  "leaderboard": [
    {
      "pundit_id": "mcafee_pat",
      "pundit_name": "Pat McAfee",
      "sport": "NFL",
      "total_predictions": 142,
      "resolved_count": 118,
      "correct_count": 71,
      "accuracy_rate": 0.601,
      "avg_brier_score": 0.22,
      "avg_weighted_score": 0.72
    }
  ],
  "total": 48
}

HTTP status	Meaning
401	Missing or invalid API key
500	Backend / BigQuery error

GET/v1/pundits/List all tracked pundits with aggregate stats

bash

curl https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/pundits/ \
  -H "x-api-key: capk_live_your_key"

json

{
  "pundits": [
    {
      "pundit_id": "mcafee_pat",
      "pundit_name": "Pat McAfee",
      "sport": "NFL",
      "total_predictions": 142,
      "resolved_count": 118,
      "correct_count": 71,
      "accuracy_rate": 0.601,
      "avg_brier_score": 0.22,
      "avg_weighted_score": 0.72
    }
  ],
  "total": 48
}

HTTP status	Meaning
401	Missing or invalid API key
500	Backend / BigQuery error

GET/v1/pundits/{pundit_id}Pundit detail with accuracy breakdown by claim category

Name	Type	Required	Description	Example
pundit_id	string	yes	Pundit slug (path param)	mcafee_pat

bash

curl https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/pundits/mcafee_pat \
  -H "x-api-key: capk_live_your_key"

json

{
  "pundit": {
    "pundit_id": "mcafee_pat",
    "pundit_name": "Pat McAfee",
    "sport": "NFL",
    "total_predictions": 142,
    "resolved_count": 118,
    "correct_count": 71,
    "accuracy_rate": 0.601,
    "avg_brier_score": 0.22,
    "avg_weighted_score": 0.72
  },
  "accuracy_by_category": [
    {
      "claim_category": "draft_pick",
      "total": 38,
      "resolved": 32,
      "correct": 21,
      "accuracy_rate": 0.656,
      "avg_weighted_score": 0.78
    }
  ]
}

HTTP status	Meaning
401	Missing or invalid API key
404	Pundit not found
422	Validation error
500	Backend / BigQuery error

GET/v1/pundits/{pundit_id}/predictionsPaginated prediction history for a pundit

Name	Type	Required	Description	Example
pundit_id	string	yes	Pundit slug (path param)	mcafee_pat
page	integer	no	Page number (default 1)	?page=2
page_size	integer	no	Records per page (1–100, default 20)	?page_size=50
status	string	no	Filter by resolution status: CORRECT, INCORRECT, PENDING	?status=CORRECT

bash

curl "https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/pundits/mcafee_pat/predictions?page=1&page_size=20&status=CORRECT" \
  -H "x-api-key: capk_live_your_key"

json

{
  "pundit_id": "mcafee_pat",
  "predictions": [
    {
      "prediction_hash": "sha256:abc123...",
      "ingestion_timestamp": "2025-04-10T08:30:00Z",
      "source_url": "https://x.com/PatMcAfeeShow/status/...",
      "raw_assertion_text": "Chase Young goes top 5",
      "extracted_claim": "Chase Young will be selected in the top 5 of the 2025 NFL Draft",
      "claim_category": "draft_pick",
      "season_year": 2025,
      "target_player_id": "chase_young_2025",
      "target_team": null,
      "resolution_status": "CORRECT",
      "resolved_at": "2025-04-25T22:00:00Z",
      "binary_correct": true,
      "brier_score": 0.09,
      "weighted_score": 0.91,
      "outcome_notes": "Selected 3rd overall by the Giants"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 142,
  "pages": 8
}

HTTP status	Meaning
401	Missing or invalid API key
422	Invalid query parameter
500	Backend / BigQuery error

GET/v1/predictions/Search predictions across all pundits with filters

Name	Type	Required	Description	Example
category	string	no	Filter by claim_category (exact match)	?category=draft_pick
status	string	no	Filter by resolution status: CORRECT, INCORRECT, PENDING	?status=PENDING
player	string	no	Substring match on target_player_name (case-insensitive)	?player=mahomes
pundit_name	string	no	Substring match on pundit_name (case-insensitive)	?pundit_name=schefter
limit	integer	no	Records per page (1–200, default 50)	?limit=100
page	integer	no	Page number (default 1)	?page=3

bash

curl "https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/predictions/?category=draft_pick&status=CORRECT&limit=25" \
  -H "x-api-key: capk_live_your_key"

json

{
  "predictions": [
    {
      "prediction_hash": "sha256:abc123...",
      "pundit_id": "mcafee_pat",
      "pundit_name": "Pat McAfee",
      "ingestion_timestamp": "2025-04-10T08:30:00Z",
      "source_url": "https://x.com/PatMcAfeeShow/status/...",
      "raw_assertion_text": "Chase Young goes top 5",
      "extracted_claim": "Chase Young will be selected in the top 5 of the 2025 NFL Draft",
      "claim_category": "draft_pick",
      "season_year": 2025,
      "target_player_id": "chase_young_2025",
      "target_player_name": "Chase Young",
      "target_team": null,
      "resolution_status": "CORRECT",
      "resolved_at": "2025-04-25T22:00:00Z",
      "binary_correct": true,
      "brier_score": 0.09,
      "weighted_score": 0.91,
      "outcome_notes": "Selected 3rd overall by the Giants"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 412,
  "pages": 17
}

HTTP status	Meaning
401	Missing or invalid API key
422	Invalid query parameter
500	Backend / BigQuery error

GET/v1/predictions/recentLatest resolved predictions across all pundits

Name	Type	Required	Description	Example
limit	integer	no	Number of predictions to return (1–100, default 20)	?limit=10

bash

curl "https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/predictions/recent?limit=10" \
  -H "x-api-key: capk_live_your_key"

json

{
  "predictions": [
    {
      "prediction_hash": "sha256:abc123...",
      "pundit_id": "schefter_adam",
      "pundit_name": "Adam Schefter",
      "ingestion_timestamp": "2025-04-12T14:00:00Z",
      "extracted_claim": "Eagles will trade their first-round pick",
      "claim_category": "trade",
      "season_year": 2025,
      "target_player_id": null,
      "target_team": "PHI",
      "resolution_status": "INCORRECT",
      "resolved_at": "2025-04-25T23:59:00Z",
      "binary_correct": false,
      "brier_score": 0.81,
      "weighted_score": 0.19,
      "outcome_notes": "Eagles did not trade their first-round pick"
    }
  ],
  "count": 10
}

HTTP status	Meaning
401	Missing or invalid API key
500	Backend / BigQuery error

GET/v1/draft/{year}Draft prediction summary for a given season year

Name	Type	Required	Description	Example
year	integer	yes	NFL draft year (path param)	2025

bash

curl https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/draft/2025 \
  -H "x-api-key: capk_live_your_key"

json

{
  "year": 2025,
  "total": 89,
  "resolved": 72,
  "pending": 17,
  "predictions": [
    {
      "prediction_hash": "sha256:abc123...",
      "pundit_id": "mcafee_pat",
      "pundit_name": "Pat McAfee",
      "ingestion_timestamp": "2025-04-10T08:30:00Z",
      "source_url": "https://x.com/PatMcAfeeShow/status/...",
      "raw_assertion_text": "Chase Young goes top 5",
      "extracted_claim": "Chase Young will be selected in the top 5 of the 2025 NFL Draft",
      "season_year": 2025,
      "target_player_name": "Chase Young",
      "target_team": null,
      "resolution_status": "CORRECT",
      "resolved_at": "2025-04-25T22:00:00Z",
      "binary_correct": true,
      "weighted_score": 0.91,
      "outcome_notes": "Selected 3rd overall by the Giants"
    }
  ]
}

HTTP status	Meaning
401	Missing or invalid API key
422	Validation error (e.g. non-integer year)
500	Backend / BigQuery error

GET/v1/draft/{year}/resultsDraft resolution scoreboard grouped by status + per-pundit accuracy

Name	Type	Required	Description	Example
year	integer	yes	NFL draft year (path param)	2025

bash

curl https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/draft/2025/results \
  -H "x-api-key: capk_live_your_key"

json

{
  "year": 2025,
  "total": 89,
  "by_status": {
    "CORRECT": [ { "pundit_name": "Pat McAfee", "extracted_claim": "...", "weighted_score": 0.91 } ],
    "INCORRECT": [ { "..." : "..." } ],
    "PENDING": [ { "..." : "..." } ]
  },
  "pundit_accuracy": [
    {
      "pundit_id": "mcafee_pat",
      "pundit_name": "Pat McAfee",
      "total_predictions": 12,
      "resolved_count": 10,
      "correct_count": 7,
      "accuracy_rate": 0.7,
      "avg_weighted_score": 0.81
    }
  ]
}

HTTP status	Meaning
401	Missing or invalid API key
422	Validation error
500	Backend / BigQuery error

GET/v1/integrity/verifyHash chain integrity check — verify the ledger has not been tampered with

Each prediction is SHA-256 hashed at ingest, including the previous record's hash. This endpoint walks the full chain and returns verified: true if all hashes match. Any modification to a historical record would break all subsequent hashes.

bash

curl https://pundit-ledger-api-wvhvx2muna-uc.a.run.app/v1/integrity/verify \
  -H "x-api-key: capk_live_your_key"

json

{
  "verified": true,
  "records_checked": 4821,
  "broken_at": null
}

HTTP status	Meaning
401	Missing or invalid API key
500	Integrity check failed to run

Errors

Common error shapes

All errors follow FastAPI's standard response format.

json

// Standard error
{ "detail": "Human-readable error message" }

// Validation error (422) — includes field-level context
{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

Need access?

API keys are provisioned through your Cap Alpha account. Sign up or sign in to get started.

Get an API key Contact support