API reference

Reports

The core resource. A report is one 4-model council run on one event: created as pending, processed in the background (~30–120s), then completed or failed (auto-refund).

Endpoints

Method	Path	Purpose
GET	/api/reports/check/{event_id}	Cache status + your cost, before spending
POST	/api/reports	Create a report (spends credits; 5 runs/hour)
GET	/api/reports/{id}	Full report — poll this until completed
GET	/api/reports	Your report history

Create

POST https://backend-production-092f.up.railway.app/api/reports
X-API-Key: pc_live_...
{"event_id": "566653", "quoted_credits": 400}   // quoted_credits optional but recommended

→ {"report_id": 57, "status": "pending", "cached": false, "credits_spent": 400}
// If a same-day cached report exists you get it instantly at half price
// (status "completed", cached: true). If you already own it: free.

The report object

GET /api/reports/{id} — completed

{
  "id": 57,
  "event_id": "566653",
  "event_title": "Fed decision in July?",
  "status": "completed",            // pending | processing | completed | failed
  "action": "BUY_NO",               // verdict on the QUERIED market only
  "probability": 5.0,               // % for the queried market
  "confidence": 75.0,
  "summary": "Council recommends …",
  "created_at": "…", "completed_at": "…",
  "council_config": {
    "runtime": { /* the source of truth — below */ },
    "requested": {"models": ["grok","claude","gpt","gemini"]}
  },
  "deliberation": { /* full 3-stage data: opinions, cross-review, synthesis */ }
}
// Provider $ costs are intentionally absent from every response.

council_config.runtime — what you reason over

{
  "models": ["gpt", "grok", "claude"],       // who actually participated
  "chairman": "grok",
  "degraded": true,                           // a requested model dropped out
  "provider_failures": {"gemini": "503 …"},  // why, per model

  "most_likely_outcome": "No change",         // the headline answer
  "most_likely_probability": 64,
  "most_likely_source": "council",            // or "market_implied" — see flags
  "consensus_market_conflict": false,
  "market_probabilities": {                   // full consensus distribution
    "No change": 64, "25 bps cut": 30, "50+ bps cut": 6
  },

  "top_bets": [{                              // ranked suggestions w/ payout math
    "side": "BUY_YES",                        // or BUY_NO
    "market": "25 bps cut",
    "kind": "edge",                           // "edge" = mispricing | "pick" = fair-price favorite
    "yes_price": 0.105,                       // live Polymarket YES price (0-1)
    "share_cost": 0.105,
    "consensus_probability": 30,              // council %
    "market_implied_probability": 11,         // from price
    "edge_points": 19,
    "win_probability": 30,
    "payout_per_dollar": 8.52,                // net $ per $1 staked if right
    "expected_return_per_dollar": 1.96,
    "slug": "fed-25-bps-cut"                  // Polymarket deep link
  }],
  "best_edge": { /* == top_bets[0], back-compat */ }
}

Two flags your agent must respect

Flag	Meaning	What to do
consensus_market_conflict: true	The council's distribution disagreed hard with market prices; the headline fell back to the market-implied favorite and bet suggestions were suppressed	Treat the report as low-conviction; do not synthesize your own bets from the distribution
degraded: true	One or more requested models didn't participate (check provider_failures)	Weigh the verdict accordingly; consensus of 3 ≠ consensus of 4

Verdict semantics

On multi-outcome events, action applies to the single queried market and is often SKIP even when the report is valuable — the real signal is most_likely_outcome + market_probabilities + top_bets. kind: "edge" bets claim a mispricing; kind: "pick" bets are the council's favorite at fair price (no claimed edge). Reports also get graded publicly after resolution — GET /api/stats/track-record.