{"openapi":"3.1.0","info":{"title":"Scopes Read API","version":"1.0.0","description":"Independent prediction-market fair value, divergences, calibration record, and dataset coverage. Free tier is delayed (~24h) and computed-summary only; live data and the full archive require a subscription. Every response returns the terms URL in the X-Scopes-Terms header.","termsOfService":"https://scopes.com/terms","contact":{"name":"Scopes support","url":"https://scopes.com/terms"}},"servers":[{"url":"https://scopes.com/api/v1","description":"v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Optional today; required for higher limits / live data when API keys ship. Send `Authorization: Bearer <key>`."}},"schemas":{"Divergence":{"type":"object","properties":{"outcome_id":{"type":"integer","description":"Stable key — chain to /series (?outcome=)."},"event":{"type":"string"},"outcome":{"type":"string"},"desk":{"type":["string","null"]},"kalshi_prob":{"type":["number","null"]},"polymarket_prob":{"type":["number","null"]},"scopes_fair_value":{"type":["number","null"]},"scopes_divergence":{"type":["number","null"]},"computed_at":{"type":"string","format":"date-time"},"category":{"type":["string","null"]},"series_available":{"type":"boolean","description":"False for rate-desk outcomes (series withheld pending licensing)."},"resolves_at":{"type":["string","null"]}}},"DivergencesResponse":{"type":"object","properties":{"delayed":{"type":"boolean"},"delay_note":{"type":"string"},"count":{"type":"integer"},"divergences":{"type":"array","items":{"$ref":"#/components/schemas/Divergence"}}}},"OutcomeItem":{"type":"object","properties":{"series_ref":{"type":"object","description":"How to fetch this market's series from /series. Either {by:\"outcome\",outcome_id} or {by:\"ticker\",desk,ticker}."},"outcome_id":{"type":["integer","null"],"description":"Set for outcome-keyed desks (rates/polls)."},"ticker":{"type":["string","null"],"description":"Set for ticker-keyed desks (sports/stocks/energy)."},"desk":{"type":"string"},"event":{"type":"string"},"outcome":{"type":"string"},"status":{"type":"string"},"resolves_at":{"type":["string","null"],"format":"date-time"},"series_available":{"type":"boolean","description":"False where series are withheld pending licensing (rates)."}}},"OutcomesResponse":{"type":"object","properties":{"desks":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"count":{"type":"integer"},"outcomes":{"type":"array","items":{"$ref":"#/components/schemas/OutcomeItem"}}}},"SeriesPoint":{"type":"object","properties":{"t":{"type":"string","format":"date-time","description":"Capture timestamp."},"kalshi_prob":{"type":["number","null"]},"polymarket_prob":{"type":["number","null"]},"scopes_fair_value":{"type":["number","null"]},"scopes_fair_value_2":{"type":["number","null"],"description":"Second fair line where a desk runs two models."},"scopes_divergence":{"type":["number","null"],"description":"Max |market − fair| across venues at this point."}}},"SeriesResponse":{"type":"object","properties":{"outcome_id":{"type":"integer","description":"Set for outcome-keyed desks."},"ticker":{"type":"string","description":"Set for ticker-keyed desks."},"desk":{"type":"string"},"event":{"type":"string","description":"Outcome-keyed only."},"outcome":{"type":"string","description":"Outcome-keyed only."},"point_in_time":{"type":"boolean"},"as_of":{"type":"string","format":"date-time","description":"Effective cutoff actually applied."},"requested_as_of":{"type":["string","null"],"description":"What the caller asked for (may be clamped)."},"clamped":{"type":"boolean","description":"True if as_of was ahead of what this tier may see."},"delayed":{"type":"boolean"},"delay_note":{"type":["string","null"]},"window":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"days":{"type":"integer"}}},"methodology_version":{"type":["string","null"],"description":"Fair-value method identifier."},"tier":{"type":"string"},"count":{"type":"integer"},"series":{"type":"array","items":{"$ref":"#/components/schemas/SeriesPoint"}}}},"CalibrationResponse":{"type":"object","description":"Computed calibration over resolved flags: counts, binomial significance, paired Brier, and the filters echoed back.","properties":{"n":{"type":"integer"},"fairRight":{"type":"integer"},"marketRight":{"type":"integer"},"meanBrierMarket":{"type":["number","null"]},"meanBrierFair":{"type":["number","null"]}}},"ConvergenceResponse":{"type":"object","description":"Intraday divergence-convergence study. Free tier uses a trailing 30-day window.","properties":{"contracts":{"type":"integer"},"windowedDays":{"type":["integer","null"]},"triggerCount":{"type":"integer"},"convergenceCount":{"type":"integer"},"pValue":{"type":"number"}}},"CoverageResponse":{"type":"object","properties":{"total_snapshots":{"type":"integer"},"collecting_since":{"type":["string","null"],"format":"date-time"},"desks":{"type":"object","additionalProperties":{"type":"object","properties":{"days":{"type":"integer"},"snapshots":{"type":"integer"}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/divergences":{"get":{"operationId":"getDivergences","summary":"Widest market-vs-fair-value divergences (delayed ~24h sample)","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":8}}],"responses":{"200":{"description":"Delayed divergence sample","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivergencesResponse"}}}},"429":{"description":"Daily rate limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outcomes":{"get":{"operationId":"listOutcomes","summary":"Discover markets to feed /series across all desks (by desk, status, text)","description":"Cold-start discovery across BOTH series axes: each row has a series_ref — {by:\"outcome\",outcome_id} for rates/polls, or {by:\"ticker\",desk,ticker} for sports/stocks/energy — to pass to /series. Rows carry series_available:false where series are withheld pending licensing (rates). Ticker-desk discovery scans recent history, so long-resolved markets may not appear.","parameters":[{"name":"desk","in":"query","required":false,"schema":{"type":"string","enum":["polls","rates","sports","stocks","energy"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","resolved","all"],"default":"all"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Text match on the market label/ticker."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Matching markets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomesResponse"}}}},"429":{"description":"Daily rate limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series":{"get":{"operationId":"getSeries","summary":"Point-in-time series for one market (price + Scopes Fair Value + Scopes Divergence)","description":"Identify the market EITHER by `outcome` (rates/polls) OR by `ticker`+`desk` (sports/stocks/energy) — from /outcomes or /divergences. FLAGSHIP: pass `as_of` for a point-in-time-correct view — ONLY data captured at or before that timestamp, no lookahead. A pinned past `as_of` on a paid key is reproducible (same inputs → same series), so a result is citable. Free/anon callers are delayed ~24h and limited to a trailing 30-day window; a subscription unlocks live data and more history. Unlicensed desks (rates) are withheld (HTTP 403 `desk_unavailable`).","parameters":[{"name":"outcome","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Outcome id (rates/polls). Provide this OR ticker+desk."},{"name":"ticker","in":"query","required":false,"schema":{"type":"string"},"description":"Kalshi ticker (sports/stocks/energy) — pair with desk."},{"name":"desk","in":"query","required":false,"schema":{"type":"string","enum":["sports","stocks","energy"]},"description":"Required when using ticker."},{"name":"as_of","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"ISO 8601 cutoff. Only data captured at or before this instant is returned (no lookahead). A future value, or one past a free caller’s delay, is clamped down — never up. Omit for the latest visible data."},{"name":"since","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":120},"description":"Trailing window in days, anchored to `as_of`. Capped by tier (free: 30)."}],"responses":{"200":{"description":"Point-in-time series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeriesResponse"}}}},"400":{"description":"Missing/invalid identifier (need outcome, or ticker+desk) or malformed as_of","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Desk not available via API (licensing)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown outcome id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Daily rate limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calibration":{"get":{"operationId":"getCalibrationSummary","summary":"Calibration record (market vs. fair value, with significance)","parameters":[{"name":"desk","in":"query","required":false,"schema":{"type":"string"}},{"name":"family","in":"query","required":false,"schema":{"type":"string"}},{"name":"minGap","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":1}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Calibration summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalibrationResponse"}}}}}}},"/convergence":{"get":{"operationId":"getConvergence","summary":"Intraday divergence-convergence study (trailing 30-day window)","parameters":[{"name":"gap","in":"query","required":false,"schema":{"type":"number"},"description":"Trigger gap, points (1–30)."},{"name":"target","in":"query","required":false,"schema":{"type":"number"},"description":"Convergence target gap, points (0.5–20)."},{"name":"tauH","in":"query","required":false,"schema":{"type":"number"},"description":"Time-to-close horizon, hours (0.25–240)."}],"responses":{"200":{"description":"Convergence study result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvergenceResponse"}}}}}}},"/coverage":{"get":{"operationId":"getCoverage","summary":"Dataset coverage: total snapshots and per-desk depth","responses":{"200":{"description":"Coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageResponse"}}}}}}},"/health":{"get":{"operationId":"getHealth","summary":"Pipeline freshness/status","responses":{"200":{"description":"Healthy"},"503":{"description":"Stale"}}}}}}