Developer documentation

spartanboxing API v1

Read-only REST API exposing every piece of data behind the portal — live picks, sizing, CLV evolution, model internals, audit reports, and a schema browser. Designed for programmatic trading on Polymarket and sportsbooks, dashboards, and quant research.

45 endpoints3 public42 authenticatedJSON catalog Sign in to mint a key

Browsing this catalog requires no account. Calling authenticated endpoints does — generate a key in seconds and start hitting /api/v1 from your bot, notebook, or terminal.

Quick start

Two minutes from zero to your first authenticated request.

Check health (no auth)

curl https://spartanboxing.ai/api/v1/health

Generate a personal API key

Create an account or sign in to mint sbp_... tokens. The plaintext is shown once and never stored.

Pull live picks (authenticated)

curl -H "Authorization: Bearer sbp_..." \
  "https://spartanboxing.ai/api/v1/picks/live?bankroll=10000&bet_only=true"

Authentication

Send your sbp_... token in either header below. Endpoints tagged public skip auth entirely (health, policy, this catalog).

Authorization: Bearer sbp_<32 chars>
# or
X-API-Key: sbp_<32 chars>

Invalid/revoked → 401 invalid_key. Storage is hash-only (SHA-256): we can verify but never reveal your token.

Response envelope

Every response — success or failure — has the same outer shape.meta.cron_age_minutes tells you how stale the underlying pipeline data is.

{
  "ok": true,
  "data": "<endpoint-specific>",
  "meta": {
    "generated_at": "ISO timestamp",
    "api_version": "v1",
    "model_version": "lgbm_ens_v5_YYYY-MM-DD (when applicable)",
    "cron_age_minutes": "minutes since last successful predict-live cron"
  }
}

{
  "ok": false,
  "error": {
    "code": "snake_case",
    "message": "human-readable"
  },
  "meta": {
    "generated_at": "ISO",
    "api_version": "v1"
  }
}

Polymarket / sportsbook integration notes

pricing_unitsPolymarket prices in USDC per share, equivalent to implied probability in [0, 1]. Use `implied_prob_raw` (or `implied_prob_vigfree` for sportsbook-style markets) from each pick instead of decimal_odds. Decimal odds and American odds are also surfaced on optimizer endpoints (`decimal_odds` + `american_odds`) for traders syncing across both pricing conventions.

mappingfight_id is internal to this system. To trade on Polymarket, maintain your own fight_id ↔ Polymarket condition_id mapping. The fighter_a / fighter_b strings + fight_date should be enough to match. Use /api/v1/fighters?search=name to look up canonical fighter_ids.

latencyLive cron runs every 5 min; freshness reported in meta.cron_age_minutes. Poll at any cadence — the underlying data refreshes at most 5 minutes stale.

edge_decayMedian CLV decays ~1pp per hour as the close approaches. The `best_market.clv_vs_close` field on settled picks quantifies historical alpha decay. Bet quickly when BET appears.

stake_cap_warningmax_bet_pct=0 removes the audit-derived 3% cap. Useful for low-Kelly bankrolls but very risky on long-tail underdogs (Kelly raw can ask for 30%+ of bankroll on extreme value).

book_filteringOptimizer endpoints (arbitrage, plus-ev, hedge) and /picks/live all accept a `books` CSV param. Call /api/v1/bookmakers once to discover the valid book keys for your region, then pin a comma-separated list to every subsequent request to scope results to the sportsbooks you actually have accounts at.

arbitrage_executionAn arbitrage opportunity only holds if both legs fill at the listed prices. Boxing arbs typically persist for hours (vs seconds in NBA/NFL), but partial fills do happen. The optimizer/arbitrage `recommended_first_leg` field tells you which leg to place first — always the softer book, since soft books reprice slower and a sharp-side fill that triggers a soft-side move leaves you stranded.

Discovery & health

Self-describing endpoints with no auth. Use to detect freshness, model version, and the production decision policy before pulling picks.

GET/api/v1/health public

Pipeline health & freshness

Cron freshness (age of last successful predict-live run), the active production model version, and current counts of pending vs settled live picks. Returns `status: "healthy"` only when the cron has succeeded in the last 30 min (6 missed ticks at the 5-min cadence) AND a model version is loaded.

Example request

curl 'https://spartanboxing.ai/api/v1/health'

Example response data

{
  "status": "healthy",
  "cron": {
    "last_ok_started_at": "2026-05-22T06:34:56Z",
    "age_minutes": 3
  },
  "model": {
    "version": "lgbm_ens_v5_2026-05-22",
    "fit_at": "2026-05-22T05:00:00Z"
  },
  "counts": {
    "pending_live_picks": 22,
    "settled_live_picks": 1431,
    "predictions_last_24h": 188
  }
}

Try it in a new tab

GET/api/v1/policy public

Production decision policy

The exact gates that turn a prediction into a BET: minimum vig-removed edge, maximum ensemble σ, recommended Kelly fraction and per-bet cap. Re-implement these client-side to replicate the BET/NO BET decision without round-tripping to `/picks/live`.

Example request

curl 'https://spartanboxing.ai/api/v1/policy'

Example response data

{
  "thresholds": {
    "min_edge_pp": 0.03,
    "max_uncertainty_std": null,
    "kelly_fraction_default": 0.25,
    "max_bet_pct_default": 0.03
  },
  "model_version_prefix": "lgbm_ens_v5",
  "audit_report": "master.audit_report kind='sizing_strategy' (boxing-poe): the optional confidence gate trades volume for per-bet quality; default bets every pick clearing the 3% edge floor. Per-setting Sharpe/return/drawdown recompute live in the backtest simulator."
}

Try it in a new tab

GET/api/v1/docs public

JSON descriptor of this API

Machine-readable catalog of every endpoint, query parameter, and response envelope. Same data as `/portal/api` but in JSON form for tooling.

Example request

curl 'https://spartanboxing.ai/api/v1/docs'

Try it in a new tab

Picks & decisions

Pending and settled picks with full pricing, Polymarket-aware implied probabilities, and Kelly sizing. The actionable surface for live trading.

GET/api/v1/picks/live bearerUI

Pending live picks with sizing

Every fight with a pending prediction. Each pick includes the model's fair probability for A win, B win, AND draw (3-class A/B/Draw output from lgbm_ens_v5), the best book + price, raw implied probability, vig-removed implied probability, edge in percentage points, ensemble σ, BET/NO BET verdict with reasons, and (when `bankroll` is provided) a Kelly stake recommendation. Set `include_books=true` to receive the full per-book pricing table plus per-book recomputed stakes (each at that book's price, respecting the per-book min-edge gate).

Parameters

Name	In	Type	Default	Description
bankroll	query	number	0	USD bankroll for stake math. 0 disables sizing.
kelly_fraction	query	number	0.25	Multiplier on raw Kelly f*. 0.25 = Quarter Kelly.
kelly_z	query	number	0	σ shrink: p_used = max(0.001, fair − z·σ). 0 = naive Kelly (audit-recommended).
max_bet_pct	query	number	0.03	Per-bet stake cap as fraction of bankroll. 0 disables.
min_edge_pp	query	number	0.03	Minimum vig-removed edge to qualify as BET.
max_uncertainty	query	number	none (no gate)	Maximum ensemble σ to qualify as BET. Default is no gate. Pass 0.010 to apply the tight filter.
bet_only	query	boolean	false	Drop NO BET rows from response.
include_stale	query	boolean	false	Include picks the cron stopped refreshing (likely dropped from OddsAPI).
include_books	query	boolean	false	Include full per-book pricing table per pick.
books	query	string	—	CSV of sportsbook keys (e.g. `pinnacle,draftkings,fanduel`) to restrict the per-book `books[]` array to. The BET/NO BET decision is UNCHANGED — production policy was audited against global execution. To filter BET eligibility against only YOUR books, use `/api/v1/optimizer/plus-ev` instead.

Notes

›Stale = predicted before (last_cron_started − 20 min grace). At the 5-min cadence this is 4 missed ticks of slack.
›Picks are sorted: BET-eligible first (by stake desc), then NO BET (by edge desc), then stale.
›Use `/api/v1/bookmakers` to discover valid book keys for the `books` param.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/picks/live'

GET/api/v1/picks/settled bearerUI

Settled live picks (P&L reconciliation)

Live picks where the fight has finished and the result is graded. Includes the best price the model recommended vs the closing price for CLV computation, and a `hit` boolean. Use for tracking realized P&L and validating CLV over time.

Parameters

Name	In	Type	Default	Description
since	query	string	7 days ago	ISO date — only picks predicted on or after this date.
limit	query	integer	100	Max rows. Hard cap 500.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/picks/settled'

GET/api/v1/picks/{fight_id} bearerUI

Single pending pick with per-book stakes

Detailed view of one pending pick: model breakdown, every quoted book on the picked side, and per-book Kelly stake suggestions. Returns 404 if there's no pending prediction for `fight_id`.

Parameters

Name	In	Type	Default	Description
fight_id*	path	integer	—	Internal fight identifier (see /api/v1/picks/live or /api/v1/schemas/master/fight).
bankroll	query	number	0	Same as /picks/live.
kelly_fraction	query	number	0.25	Same as /picks/live.
kelly_z	query	number	0	Same as /picks/live.
max_bet_pct	query	number	0.03	Same as /picks/live.
min_edge_pp	query	number	0.03	Same as /picks/live.
max_uncertainty	query	number	none	Same as /picks/live.
books	query	string	—	CSV of sportsbook keys to restrict the per-book `books[]` array to. Global best_market / median_market / worst_market are unchanged.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/picks/12345'

GET/api/v1/picks/historical bearerUI

Walk-forward historical picks

Every walk-forward / holdout / live pick the requested model has emitted on graded fights, with best price, edge, CLV, and hit/miss. Powers the backtest simulator. Filter by `model` (default lgbm_ens), `kind` (dev | holdout | live | all), and `limit`.

Parameters

Name	In	Type	Default	Description
model	query	string	lgbm_ens	One of: lgbm_ens (production), lgbm, pca, baseline.
kind	query	string	all	Filter by prediction_kind. One of: dev, holdout, live, all.
limit	query	integer	1000	Max rows returned. Hard cap 10000.

Notes

›Only fights with `result IN ('a_win', 'b_win')` AND `date <= CURRENT_DATE` are returned — bogus future-dated wiki imports are filtered.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/picks/historical'

GET/api/v1/picks/{fight_id}/explain bearerUI

Per-feature contribution decomposition

Linearized contribution of each input feature (SHAP-style for LightGBM ensemble models) to the model's fair probability for this fight. Use to sanity-check why the model favored one side.

Parameters

Name	In	Type	Default	Description
fight_id*	path	integer	—	Fight identifier.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/picks/12345/explain'

Bet Optimizer

Cross-book arbitrage scanning, +EV ranking by ROI per dollar, and equal-profit hedge calculation. Every endpoint respects an optional `books` CSV so callers see only opportunities executable at the sportsbooks they actually have accounts at.

GET/api/v1/optimizer/arbitrage bearerUI

Cross-book arbitrage scanner

For every pending pick, finds the best decimal price on each side across the user's book set. When `1/best_a + 1/best_b < 1`, the spread is an arbitrage that returns the same net on each outcome — a positive result only if both legs fill at the quoted prices (execution and counterparty risk apply; figures are modeled, not assured). Returns one row per opportunity with both legs, the inverse sum, the modeled profit %, and (when `outlay > 0`) a stake split that targets the same gross on each outcome. `recommended_first_leg` flags the leg to place first to reduce partial-fill risk: softer book first since softs reprice slower than sharps.

Parameters

Name	In	Type	Default	Description
books	query	string	—	CSV of sportsbook keys (e.g. `pinnacle,draftkings,fanduel`) to consider. Omit = all books. An arb at three books you don't have accounts at isn't an opportunity — always set this.
min_profit_pct	query	number	0	Drop opportunities with a modeled profit below this %. Useful to filter out paper-thin spreads whose margin may not cover bet limits or execution slippage.
outlay	query	number	—	Total $ outlay to size the stake split against. When set, each opportunity includes a `recommended_split` with leg_picked / leg_opposite stakes and the equal modeled payout (if both legs fill).

Notes

›Boxing arbs typically persist for HOURS — sometimes days — when a soft book drifts off consensus. NBA/NFL arbs vanish in seconds.
›Same-book arbs are filtered out (the math holds but they're not actionable cross-book opportunities).
›Only pending fights with `date >= today UTC` and a model prediction are scanned. Use /api/v1/picks/live first if you need to verify the underlying pick.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/optimizer/arbitrage'

Example response data

{
  "fight_id": 12345,
  "fight_date": "2026-05-31",
  "fighter_a": "Karen Chukhadzhian",
  "fighter_b": "Paddy Donovan",
  "leg_picked": {
    "side": "a",
    "fighter": "Karen Chukhadzhian",
    "book": "betfair_ex_eu",
    "book_classification": "sharp",
    "decimal_odds": 2.18,
    "american_odds": 118,
    "implied_prob_raw": 0.4587
  },
  "leg_opposite": {
    "side": "b",
    "fighter": "Paddy Donovan",
    "book": "betmgm",
    "book_classification": "soft",
    "decimal_odds": 1.95,
    "american_odds": -105,
    "implied_prob_raw": 0.5128
  },
  "inverse_sum": 0.9715,
  "profit_pct": 2.85,
  "recommended_first_leg": "leg_opposite",
  "recommended_split": {
    "leg_picked_stake_dollars": 235.78,
    "leg_opposite_stake_dollars": 263.42,
    "total_outlay_dollars": 499.2,
    "locked_payout_dollars": 513.42,
    "locked_profit_dollars": 14.22
  }
}

GET/api/v1/optimizer/plus-ev bearerUI

+EV opportunities ranked by ROI per dollar

Every model-positive opportunity sorted by `edge / implied_vigfree` — the dollar return per unit of risk capital, not raw edge in percentage points. A 5% edge at decimal odds 1.33 (-300) is a worse bet than a 5% edge at decimal odds 3.00 (+200) because total dollar return per unit risk differs. Compared to `/picks/live`, this endpoint relaxes the strict BET gate so opportunities the production policy rejects (e.g. high σ, low absolute edge) still surface for the user to size with their own discretion.

Parameters

Name	In	Type	Default	Description
books	query	string	—	CSV of sportsbook keys to consider. Omit = all books.
min_edge_pp	query	number	0	Minimum vig-removed edge (in fraction, e.g. 0.02 = 2%) to include.
max_uncertainty	query	number	1	Maximum ensemble σ to include. Default 1.0 = no gate; pass 0.010 to apply the production gate.
bankroll	query	number	0	USD bankroll for Kelly stake sizing. 0 disables sizing.
kelly_fraction	query	number	0.25	Kelly multiplier (audit recommends 0.25 = Quarter Kelly).
kelly_z	query	number	0	σ shrink: p_used = max(0.001, fair − z·σ). 0 = naive Kelly (production default).
max_bet_pct	query	number	0.03	Per-bet stake cap as fraction of bankroll. 0 disables cap.

Notes

›`roi_per_dollar` is the correct sort key for capital efficiency, not raw `edge_pp`.
›Books that quote only one side fall back to raw implied (best.impliedRaw) instead of vig-removed — conservative; understates edge slightly.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/optimizer/plus-ev'

GET/api/v1/optimizer/hedge bearerUI

Equal-profit hedge calculator

Given a bet you've already placed (`stake` on `side` of `fight_id` at decimal `odds`), returns the stake H on the opposite side that evens out the net P/L across outcomes if the hedge fills. Math: `H = stake × odds / opposite_odds`. Opposite-side price is selected as the best across the user's `books` filter (or all books if omitted). A negative `locked_profit` means the hedge nets a loss — still useful for capping downside on a now-stale bet. All figures are modeled and depend on execution; they are not assured.

Parameters

Name	In	Type	Default	Description
fight_id*	query	integer	—	Internal fight identifier (see /api/v1/picks/live).
stake*	query	number	—	USD amount you've already wagered (must be > 0).
odds*	query	number	—	Decimal odds your bet is locked in at. Must be > 1. (e.g. 2.10 for +110.)
side*	query	string	—	Which side of the fight you bet. Must be `a` or `b`.
books	query	string	—	CSV of sportsbook keys to consider for the opposite-side quote. Omit = all books.

Notes

›Returns 404 `fight_not_found` if the fight has settled or no live pick exists for it.
›Returns 404 `no_hedge_quote` if no book in the (possibly filtered) set has a usable opposite-side price.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/optimizer/hedge'

Example response data

{
  "fight_id": 12345,
  "fight_date": "2026-05-31",
  "fighter_a": "Karen Chukhadzhian",
  "fighter_b": "Paddy Donovan",
  "your_bet": {
    "side": "a",
    "fighter": "Karen Chukhadzhian",
    "stake_dollars": 100,
    "decimal_odds": 2.5,
    "american_odds": 150
  },
  "hedge": {
    "side": "b",
    "fighter": "Paddy Donovan",
    "book": "fanduel",
    "decimal_odds": 2,
    "american_odds": 100,
    "stake_dollars": 125
  },
  "outcome": {
    "total_outlay_dollars": 225,
    "gross_payout_dollars": 250,
    "locked_profit_dollars": 25,
    "locked_roi": 0.1111
  }
}

Closing Line Value

CLV measurements across the universe (devig vs raw close, decay over time, bootstrap CIs). These are the headline edge metrics.

GET/api/v1/clv/evolution bearerUI

CLV decay over time-to-commence

Median CLV bucketed by how many minutes before fight start the prediction was made. Quantifies alpha decay — bet earlier when CLV is highest. Includes per-fight trajectories and an overall aggregate.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/clv/evolution'

GET/api/v1/clv/devig bearerUI

Vig-removed CLV (production headline)

CLV computed against the consensus vig-free closing line rather than the raw best price. Sliced by sharpness universe (sharp books / all books). This is the headline number we report for the model.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/clv/devig'

GET/api/v1/clv/openclose bearerUI

Open vs close CLV anchored at first quote

CLV computed against the first observed open quote (instead of close). Validates that the model's edge exists at the moment a bet could realistically be placed.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/clv/openclose'

GET/api/v1/clv/ci bearerUI

Bootstrap confidence intervals on CLV

1000-iter bootstrap of mean CLV with 95% CI, by sharpness universe and period. Use when arguing edge is statistically distinguishable from zero.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/clv/ci'

Model introspection

Internals of the production lgbm_ens_v5 model — feature importances, rolling metrics, calibration, refit P&L, holdout audit, MC Kelly survival curves.

GET/api/v1/model/summary bearerUI

All trained model versions with headline metrics

One row per model_version (logistic_v1, lgbm_v1, lgbm_ens_v5, …) with n_train, log loss, Brier, ROC AUC, and dev CLV. Use to pick a model for `picks/historical`.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/summary'

GET/api/v1/model/comparison bearerUI

Head-to-head metrics across model families

Side-by-side comparison points for plotting model families on the same axis.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/comparison'

GET/api/v1/model/coefs bearerUI

Coefficient time series (logistic model)

Per-feature coefficient at each refit cutoff date. For the logistic baselines only — LightGBM coefficient analogs live in `/model/feature-pnl`.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/coefs'

GET/api/v1/model/rolling bearerUI

Rolling log loss / Brier / accuracy

Time-bucketed rolling out-of-sample metrics for the production model, used by the model-quality charts.

Parameters

Name	In	Type	Default	Description
window	query	integer	50	Rolling window size in predictions (1–500).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/rolling'

GET/api/v1/model/calibration bearerUI

Calibration bins with bootstrap CI

Reliability bins (predicted probability vs empirical hit rate). Tells you where the model is over/under-confident.

Parameters

Name	In	Type	Default	Description
bins	query	integer	10	Number of equal-width bins on [0, 1] (3–30).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/calibration'

GET/api/v1/model/refit-sample bearerUI

In-sample vs out-of-sample refit quality

For each walk-forward refit cutoff, in-sample vs out-of-sample log loss / Brier / CLV.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/refit-sample'

GET/api/v1/model/feature-pnl bearerUI

P&L attribution per feature

Permutation-style attribution: how much CLV is captured per feature, by period. Shows which features actually carry the edge.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/feature-pnl'

GET/api/v1/model/regression bearerUI

Per-feature univariate regression + collinearity

Single-feature regression coefficients, bin-by-bin response, stability over time, collinearity groups, and a final classification (kept / collinear / noisy).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/regression'

GET/api/v1/model/pca bearerUI

Adaptive-PCA refits (historical)

Component selection per refit for the logistic_v2_pca model family. Historical/reference only — production no longer uses PCA.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/pca'

GET/api/v1/model/mc-kelly bearerUI

Monte Carlo Kelly bankroll-growth simulations

Distribution of terminal bankroll over N simulated bet sequences for each (kelly fraction, universe) combo. Includes recommended fraction.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/mc-kelly'

GET/api/v1/model/holdout-audit bearerUI

Holdout-audit report (full)

Sealed holdout audit: period-by-period metrics, feature shift checks, book coverage, per-book overround, and seal state. The strictest test we run.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/model/holdout-audit'

Data & audit

Underlying data quality, distributions, odds-source coverage, and the resolution log for ingestion provenance.

GET/api/v1/audit/data-quality bearerUI

Master schema data quality report

Outcome coverage by year and weight class, fighter bio coverage, feature zero-rate, and totals. Used to flag silent data drift before it poisons the model.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/audit/data-quality'

GET/api/v1/audit/corpus bearerUI

Corpus health (fights, fighters, books)

Totals by date bucket — fights, fighters with bios, books quoting, dev/holdout split.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/audit/corpus'

GET/api/v1/audit/odds-comparison bearerUI

Per-book pricing comparison

Pinnacle-vs-soft pricing dispersion, overround stats, and book coverage per fight for the production model.

Parameters

Name	In	Type	Default	Description
limit	query	integer	500	Max comparison rows (10–2000).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/audit/odds-comparison'

GET/api/v1/audit/resolution-log bearerUI

Fighter-resolution provenance log

Per-fighter resolution attempts (BoxRec, BDA, Wikipedia, manual override). Tracks which source supplied which record and any conflicts.

Parameters

Name	In	Type	Default	Description
limit	query	integer	100	Max rows. Cap 500.
search	query	string	—	Case-insensitive fighter-name substring.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/audit/resolution-log'

GET/api/v1/audit/distributions bearerUI

Feature value distributions

Histograms for every input feature. Used to verify feature ranges are stable across refit cutoffs.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/audit/distributions'

Bookmakers

Catalog of every sportsbook the system tracks: region, sharp/soft classification, current pending-pick coverage, and per-book median overround (vig). Powers per-user book selection across the optimizer + picks endpoints.

GET/api/v1/bookmakers bearerUI

Catalog of all known sportsbooks

Every sportsbook the system tracks, with region (EU / UK / US / US₂ / AU / other), sharp-vs-soft classification, current pending-pick coverage, and median per-book overround (book's vig in plain percentage points). Built dynamically from the union of the static region map and any book currently quoting at least one pending pick. Use to populate a per-user book picker, dynamically filter Bet Optimizer scans, or sanity-check `books=` CSVs against books with active quotes.

Notes

›Sharp = Pinnacle, Bookmaker.eu, BetMGM, Circa, etc. Source list is `SHARP_BOOKS` in `src/lib/proof-of-edge.ts`.
›`median_overround_pp` of 0.05 = 5% vig (typical soft book). Pinnacle / sharp books typically run 2-4%.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/bookmakers'

Example response data

[
  {
    "book": "pinnacle",
    "region": "eu",
    "classification": "sharp",
    "pending_picks_quoting": 22,
    "pending_picks_paired": 22,
    "median_overround_pp": 0.0264
  },
  {
    "book": "draftkings",
    "region": "us",
    "classification": "soft",
    "pending_picks_quoting": 18,
    "pending_picks_paired": 18,
    "median_overround_pp": 0.0571
  }
]

Fighters

Per-fighter biographical and feature data backing the prediction model. List + detail endpoints.

GET/api/v1/fighters bearerUI

Paginated, searchable fighter list

All fighters in `master.fighter` with biographical fields and total-fight count. Stable sort on `fighter_id ASC` for paginated iteration; `meta.pagination.next_offset` tells you the next page offset (or `null` when at end). For deeper iteration than 100K rows, narrow via `search`.

Parameters

Name	In	Type	Default	Description
search	query	string	—	Case-insensitive name substring (ILIKE %search%). Trimmed.
limit	query	integer	100	Max rows per page. Hard cap 500.
offset	query	integer	0	Skip count for pagination. Hard cap 100000.
has_bio	query	boolean	false	When true, drop rows with no biometrics populated (no dob AND no stance AND no height AND no reach).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/fighters'

Example response data

[
  {
    "fighter_id": 1248,
    "name": "Karen Chukhadzhian",
    "source": "boxrec",
    "dob": "1996-05-23",
    "stance": "orthodox",
    "height_cm": 178,
    "reach_cm": 183,
    "nationality": "Ukraine",
    "total_fights": 28
  }
]

GET/api/v1/fighters/{fighter_id} bearerUI

Fighter detail (bio + record + resolution log)

Bio fields, current Glicko rating, full record, manual-override status, and the 50 most recent ingestion resolution attempts.

Parameters

Name	In	Type	Default	Description
fighter_id*	path	integer	—	Internal fighter identifier (see /api/v1/fighters or /api/v1/schemas/master/fighter).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/fighters/678'

Bet Journal

Per-user bet journal — log, list, settle, and analyze your bets with point-in-time model snapshots. Full CRUD + analytics aggregates.

GET/api/v1/journal/bets bearerUI

List your logged bets

Returns all bets in your journal ordered by placement date (newest first). Each bet includes the point-in-time model snapshot captured at log time, settlement status, P/L, and realized CLV where available.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/journal/bets'

Example response data

{
  "id": "uuid",
  "source": "pick",
  "fightId": 1234,
  "pickedFighter": "Oleksandr Usyk",
  "bookKey": "pinnacle",
  "decimalOdds": 1.85,
  "americanOdds": -118,
  "stake": 250,
  "currency": "USD",
  "snapshotEdge": 0.042,
  "snapshotClvAtLog": 0.038,
  "status": "won",
  "payout": 462.5,
  "realizedClv": 0.035
}

Line History

Universal line movement data for any fight. Per-book time series, market median, and summary stats. Public endpoints — no auth required.

My Bookmakers

Per-user sportsbook account management — save bookmaker credentials, VPN locations, and balances.

Admin (all users)

System-wide endpoints that cross the per-user boundary: list ALL users, ALL bets, ALL bookmakers and notification prefs, plus aggregate dashboard stats. These require the system API_TOKEN (not a per-user sbp_ key) and back an admin app/dashboard frontend with full read access to every user's data.

GET/api/v1/admin/stats bearer

System-wide dashboard stats

Aggregate counts for an admin dashboard: total/new users, bet totals (pending, settled, total stake, realized P&L, mean CLV), pipeline health (last cron run age, 24h run count, healthy flag), and v3 live/expired prediction counts. Requires the system API_TOKEN.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/admin/stats'

Example response data

{
  "users": {
    "total": 42,
    "last_7d": 5,
    "last_30d": 18
  },
  "bets": {
    "total": 310,
    "pending": 64,
    "settled": 246,
    "total_stake": 26350,
    "realized_pnl": 1240.5,
    "mean_clv": 0.031
  },
  "pipeline": {
    "last_run_age_minutes": 3,
    "last_run_ok": true,
    "runs_24h": 287,
    "healthy": true
  },
  "predictions": {
    "live": 48,
    "expired": 213
  }
}

GET/api/v1/admin/users bearer

List ALL users with stats

Every registered user with aggregate stats: bet count, pending/settled split, total stake, realized P&L, mean CLV, saved-bookmaker count, active API-key count, and notification status. Requires the system API_TOKEN.

Parameters

Name	In	Type	Default	Description
limit	query	integer	500	Max rows. Hard cap 5000.
offset	query	integer	0	Pagination offset.
search	query	string	—	Case-insensitive email/name substring filter.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/admin/users'

Example response data

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "Jane Doe",
  "createdAt": "2026-05-01T12:00:00Z",
  "betCount": 23,
  "pendingBets": 4,
  "settledBets": 19,
  "totalStake": 1955,
  "realizedPnl": 120.5,
  "meanClv": 0.028,
  "bookmakerCount": 3,
  "apiKeyCount": 1,
  "notificationsEnabled": true
}

GET/api/v1/admin/users/{userId} bearer

Full profile for one user

Complete record for a single user: account info, EVERY logged bet (with point-in-time model snapshot columns), notification preferences, saved bookmakers, and API-key metadata (prefixes only — never the raw token). Requires the system API_TOKEN.

Parameters

Name	In	Type	Default	Description
userId*	path	string	—	User UUID (from /api/v1/admin/users).

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/admin/users/{userId}'

GET/api/v1/admin/bets bearer

ALL bets across all users

Every bet in the system with the owning user's id + email joined. Paginated and filterable by status, user, or date. Meta includes total count, total stake, and mean CLV for the filtered set. Requires the system API_TOKEN.

Parameters

Name	In	Type	Default	Description
limit	query	integer	500	Max rows. Hard cap 5000.
offset	query	integer	0	Pagination offset.
status	query	string	—	Filter by status: pending \| won \| lost \| push.
user_id	query	string	—	Filter to a single user UUID.
since	query	string	—	ISO date — only bets placed on/after this date.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/admin/bets'

GET/api/v1/admin/bookmakers bearer

ALL saved bookmakers

Every saved bookmaker account across all users (book key, username, account id, VPN location, balance, currency, notes, active flag) with the owning user's email. Requires the system API_TOKEN.

Parameters

Name	In	Type	Default	Description
user_id	query	string	—	Filter to a single user UUID.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/admin/bookmakers'

GET/api/v1/admin/notifications bearer

ALL notification preferences

Every user's notification preferences (enabled flag, min edge, max uncertainty, min stake, bankroll) with the owning user's email. Requires the system API_TOKEN.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/admin/notifications'

Operations

Live cron run log and the latest persisted walk-forward backtest snapshot.

GET/api/v1/runs bearerUI

Live cron run log

Recent predict-live ticks with start time, duration, OddsAPI credits consumed, ok/failure status.

Parameters

Name	In	Type	Default	Description
limit	query	integer	25	Max rows. Cap 200.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/runs'

GET/api/v1/backtest/latest bearerUI

Latest persisted walk-forward backtest

Most recent backtest summary row: total picks, hit rate, devig CLV, Sharpe, refits, runtime.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/backtest/latest'

Schema browser

Generic read-only access to the master schema. Tables, columns, and sampled rows.

GET/api/v1/schemas bearerUI

List all schemas + tables + row counts (system token only)

Discovery endpoint for the database surface. Returns schemas (`master`, `bronze`, `public`, …) and their tables. ADMIN-ONLY: requires the system API token — per-user keys receive 403.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/schemas'

GET/api/v1/schemas/{schema}/{table} bearerUI

Columns + sample rows for one table (system token only)

Column types, nullability, and up to 100 sample rows. Read-only. ADMIN-ONLY: requires the system API token — per-user keys receive 403. Credential tables are never browsable.

Parameters

Name	In	Type	Default	Description
schema*	path	string	—	Schema name (e.g. master).
table*	path	string	—	Table name.
limit	query	integer	50	Max sample rows. Cap 100.

Example request

curl -H "Authorization: Bearer $API_TOKEN" 'https://spartanboxing.ai/api/v1/schemas/master/prediction'

Status codes

Code	When	Recovery
200	Success. data field present.	—
400	Malformed query / path param (invalid_fight_id, invalid_stake, offset_too_large, …).	Read error.code and error.message; fix the request and retry.
401	Missing, invalid, or revoked token (unauthorized, invalid_key).	Mint a new key above and resend the request.
404	Resource doesn't exist or hasn't been generated yet (fight_not_found, fighter_not_found, no_hedge_quote).	Check the underlying audit / cron has run, or remove restrictive filters.
500	Internal fetcher crashed (db_error, fetch_failed).	Retry after a few seconds. If persistent, open an issue with the request URL and timestamp.