Sports DocsResponse Format
The API returns JSON. Response shapes are endpoint-specific; there is no single wrapper such as {data, metadata} for every route.
Dates and times use:
| Field type | Format |
|---|---|
| Dates | YYYY-MM-DD |
| Game times | HH:MM:SS, Eastern Time |
| Timestamps | ISO 8601 string |
Team names in authenticated model endpoints are usually normalized slugs such as new_york_yankees. The public website endpoint formats team names for display.
Prediction Response
GET /api/v1/predictions/{sport}/{model_type}
json
{
"sport": "mlb",
"model_type": "won_on_points",
"predictions_date": "2026-05-23T14:12:05.000000",
"games": [
{
"date": "2026-05-23",
"time": "19:10:00",
"away_team": "new_york_yankees",
"home_team": "colorado_rockies",
"predictions": {
"IMPLIED": 0.3741,
"BLEND": 0.4112,
"XGB": 0.3929
},
"away_money_line": -135,
"home_money_line": 115,
"open_away_money_line": -128,
"open_home_money_line": 108,
"ev_away_ml": -3.1,
"ev_home_ml": 1.8
}
],
"models_used": ["IMPLIED", "AI", "BLEND", "CATB", "RF", "LGB", "LOGR", "XGB", "XT"]
}
Common game fields:
| Field | Meaning |
|---|---|
date | Game date |
time | Game time in Eastern Time. Important for doubleheaders. |
away_team, home_team | Normalized team names |
predictions | Model probabilities for the positive side |
Probability axes:
| Model type | Positive side | Negative side |
|---|---|---|
over_under | Over | Under |
won_on_points | Home moneyline | Away moneyline |
won_on_spread | Home spread | Away spread |
Line fields:
| Model type | Fields |
|---|---|
over_under | over_under, over_line, under_line, open_over_under |
won_on_points | away_money_line, home_money_line, open_away_money_line, open_home_money_line |
won_on_spread | away_point_spread, home_point_spread, away_point_spread_line, home_point_spread_line, open_away_point_spread, open_home_point_spread |
Opening line fields can be null when no real opener is available. Placeholder zero openers are intentionally suppressed.
EV fields are informational calculations. They are not a validated betting selector.
Public ML Predictions Response
GET /api/v1/public/ml-picks/{sport}/{market}
json
{
"sport": "mlb",
"market": "moneyline",
"model_type": "won_on_points",
"predictions_date": "2026-05-23T14:12:05.000000",
"games": [
{
"date": "2026-05-23",
"time": "19:10:00",
"away_team": "New York Yankees",
"home_team": "Colorado Rockies",
"pick": "Colorado Rockies ML",
"pick_side": "home",
"blend_probability": 0.4112,
"confidence": 0.1776,
"market_line": "ML -135/+115",
"implied_probability": 0.3741,
"lines": {
"away_money_line": -135,
"home_money_line": 115
},
"models": {
"BLEND": 0.4112,
"XGB": 0.3929
}
}
],
"models_used": ["BLEND", "XGB", "RF", "LGB", "CATB", "LOGR", "XT"],
"note": "Free ML predictions only. App workflows, MCP/CLI tools, and account features require a paid Scottfree Sports plan."
}
Odds Response
GET /api/v1/odds/{sport}
json
{
"sport": "mlb",
"date": "2026-05-23T16:00:00.000000",
"games": [
{
"match_id": "abc123",
"date": "2026-05-23",
"time": "19:10:00",
"away_team": "new_york_yankees",
"home_team": "colorado_rockies",
"away_money_line": -135,
"home_money_line": 115,
"over_under": 10.5,
"over_line": -110,
"under_line": -110,
"last_updated": "2026-05-23 15:55:00"
}
],
"last_updated": "2026-05-23T16:00:00.000000"
}
Results Response
GET /api/v1/results/{sport}/{model_type}
json
{
"sport": "mlb",
"model_type": "won_on_points",
"results": [
{
"date": "2026-05-22",
"time_est": "19:10:00",
"away_team": "new_york_yankees",
"home_team": "colorado_rockies",
"away_score": 4.0,
"home_score": 2.0,
"won_on_points": 0.0,
"BLEND": 0.4112,
"IMPLIED": 0.3741,
"open_home_money_line": 108.0,
"home_money_line": 115.0
}
],
"last_updated": "2026-05-23T14:20:00.000000"
}
Result rows are flexible. Additional model, odds, target, and feature columns can appear as model artifacts evolve.
Summary Response
GET /api/v1/summary/{sport}/{model_type}
json
{
"sport": "mlb",
"model_type": "won_on_points",
"summaries": [
{
"model": "BLEND",
"total_games": 420,
"wins": 214,
"losses": 206,
"win %": 50.95,
"win % 4W": 51.8,
"fade %": 49.05,
"home %": 52.1,
"away %": 47.9
}
],
"generated_date": "2026-05-23T14:20:00.000000"
}
The side labels are market-relative:
| Model type | Summary side fields |
|---|---|
over_under | over %, under %, over % 1W, under % 1W, over % 4W, under % 4W |
won_on_points | home %, away %, home % 1W, away % 1W, home % 4W, away % 4W |
won_on_spread | home %, away %, home % 1W, away % 1W, home % 4W, away % 4W |
Sports Data Refresh Response
GET /api/v1/scottfree-sports-data/status
json
{
"has_scottfree_sports_data": true,
"expires_at": "2026-06-13T00:00:00+00:00",
"owned_products": ["nfl_historical"],
"owned_sports": ["nfl"],
"refreshes_used": 1,
"refreshes_remaining": 7,
"refresh_limit": 8,
"next_reset_at": "2026-06-01T00:00:00+00:00"
}
POST /api/v1/scottfree-sports-data/refresh
json
{
"refreshes_remaining": 7,
"next_reset_at": "2026-06-01T00:00:00+00:00",
"downloads": [
{
"sport": "nfl",
"filename": "nfl_game_scores_1g.csv",
"url": "https://storage.googleapis.com/...",
"expires_at": "2026-05-23T16:15:00+00:00"
}
]
}
Error Response
The API error handler returns:
json
{
"error": "HTTP_401",
"detail": "Invalid or expired API key",
"timestamp": "2026-05-23T16:00:00.000000"
}
Common statuses:
| Status | Meaning |
|---|---|
400 | Bad request or invalid parameter |
401 | Missing, invalid, expired, or revoked API key |
403 | Valid key, insufficient plan permission |
404 | Data artifact not available |
429 | Rate limit or quota exceeded |
500 | Server error |
503 | Dependency unavailable |