API Reference
The F1 Intelligence Platform’s read-only API: Hono on Cloudflare Workers (apps/api/).
Base URL: https://f1-api.gorkemkaryol.dev
Local dev: http://localhost:8787
All responses follow this envelope:
{ "data": <T>, "error": null }
{ "data": null, "error": { "code": "ERROR_CODE", "message": "..." } }
No authentication. All endpoints are read-only GET.
Caching: every route’s Cache-Control comes from the data it returns, never from a client
parameter (apps/api/src/common/route.ts, rules in common/cache.ts):
- Race-scoped routes (
/api/races/:id/*,/api/predictions/race/:raceId*,/api/sprint/race/:raceId*):public, max-age=86400, immutableonce the race iscompleted, otherwisepublic, max-age=600. - Season-scoped routes (
?year=Nlists, and/api/drivers/:id*//api/teams/:id*, whose ids belong to one season): immutable for a past season, 10 min for the current one. For the:idroutes the season is the driver’s/team’s own:?year=never changes the lifetime. Careers use their newest season. - Reference data (
/api/seasons,/api/search,/api/races/circuits,/api/races/circuit/:key,/api/predictions/model-info):public, max-age=3600. - In-progress answers above are
public, max-age=600from Friday to Monday 12:00 UTC, when the ETL ingests (isIngestWindow), andpublic, max-age=3600between race weekends. - Upcoming (
/api/predictions/upcoming,/api/sprint/upcoming): by the race’s status, like race-scoped routes./api/predictions/accuracyspans every season, so it always uses the in-progress lifetime. - History (
/api/history/*,/api/drivers/:id/history,/api/teams/:id/history):public, max-age=86400(not immutable: F1DB updates after each race)./api/races/circuit/:key/telemetryfollows the lap’s season. - An empty answer (no rows yet, enrichment not backfilled) is always cached for 10 min only.
edgeCache() (common/edge-cache.ts, the Cloudflare Cache API, ADR 0005) sits in front of every /api/*
handler and stores any 200 whose Cache-Control is public, per data centre. It only works on the custom
domain (a no-op on *.workers.dev). Each copy is kept 30 days past its max-age: a lapsed copy is refreshed
from Neon, but still answers when that refresh fails with a 5xx (e.g. Neon Free suspended for the month).
The cache key is the path plus only the query params the route reads (common/query-params.ts), in a fixed
order: /api/races/7?utm=x and /api/races/7 share one copy. Behind it, snapshotStore() keeps one global
copy per key in R2 until the next write window (ADR 0013); answers from it carry x-snapshot: hit.
A non-numeric :id / :raceId (or one with leading zeros) answers 400 INVALID_ID, a non-numeric year 400 INVALID_YEAR, an
unknown session 400 INVALID_SESSION, a bad date 400 INVALID_DATE, and an unknown race, driver or
team 404 NOT_FOUND.
Health
GET /api/health
Answers without touching the DB, so uptime checks never wake Neon.
{
"data": {
"status": "ok",
"timestamp": "2026-06-04T12:00:00.000Z"
}
}
GET /api/health/db
Checks DB connectivity ("db": "connected"), or 503 DB_ERROR. Wakes Neon: not for uptime monitors.
Dev only: 404 in production.
Seasons
GET /api/seasons
Returns every season, newest first, with its number of races.
{
"data": [
{ "year": 2026, "raceCount": 24 },
{ "year": 1980, "raceCount": 14 }
]
}
Races
GET /api/races?year=N&status=S
| Param | Required | Default | Notes |
|---|---|---|---|
year | no | current year | |
status | no | all | scheduled | sprint_qualifying_done | sprint_done | qualifying_done | completed |
Returns all races for the year (by race_date), oldest first; an unknown status is ignored. Each race includes eventFormat, hasSprint, sprintDate, and sprint condition fields for sprint weekends.
GET /api/races/:id
Returns a single race: { race, results, qualifying, laps } (race embeds its circuit; results is
empty until the race is completed).
laps (the same rule for the sprint detail’s laps): one { driverId, driver, fastestLapMs, avgLapMs, totalLaps } per driver, fastest first. Pit in/out laps and laps without a time are left out of all
three numbers, so totalLaps counts clean timed laps only. All three are integers.
The Race object includes:
status: the Race Status (scheduled…completed);raceDateUtc: the GP start time, or nulleventFormat:conventional|sprint|sprint_qualifying|sprint_shootouthasSprint: boolean derived from eventFormatsprintDate/sprintQualifyingDate: ISO strings, null for conventional weekendssprintWeather,sprintSafetyCarLaps,sprintVscLaps,sprintAirTempAvg,sprintTrackTempAvg,sprintHumidityAvg: sprint-specific conditions
GET /api/races/:id/long-runs
Each driver’s quickest practice long run (fp2_long_run_times), fastest first: [{ driver, compound, sessionType, medianLapMs, stintLength, deltaToFastestMs }].
medianLapMs is adjusted to a MEDIUM baseline. sessionType is FP2, or FP1 on sprint weekends. Shown on the race
page’s Long Runs tab; the GP model doesn’t use it (weighted-v4 dropped long runs, ADR 0010). 404 if the race doesn’t exist.
GET /api/races/:id/race-control
Returns race-control messages (flags, safety car/VSC, incidents) for a race, ordered by
timestamp ascending. Covers 2018+: OpenF1 for completed races from 2023 onward (empty until
ingest_race_control has run), FastF1’s race control feed for 2018–2022.
GET /api/races/:id/overtakes
Returns on-track overtakes for a race, ordered by timestamp ascending. overtakingDriverId/
overtakenDriverId reference drivers.id (already resolved from OpenF1’s car numbers):
look them up in the race’s own results/qualifying response rather than re-fetching driver
details. Empty until ingest_overtakes has run: OpenF1 only, so 2023+ and completed races only
(no source before 2023).
GET /api/races/:id/team-radio
Returns team radio clips for a race, ordered by timestamp ascending. driverId references
drivers.id (resolved from OpenF1’s car number): look it up the same way as overtakes.
recordingUrl points directly at F1’s own CDN. F1 doesn’t release radio for every session,
so an empty or partial list is expected, not an error: and since 2026 F1 releases far fewer clips.
All three race-event routes take ?session=race|sprint (default race): both sessions of a
sprint weekend share one race_id, and each row carries its session_type. Any other value → 400
INVALID_SESSION.
GET /api/races/:id/strategy?session=race|sprint
Tyre strategy for one session, drivers in finishing order (race_results or sprint_results):
{ "source": "openf1", "drivers": [{ "driver": { "...": "Driver" }, "finishPosition": 1,
"stints": [{ "stintNumber": 1, "compound": "MEDIUM", "lapStart": 1, "lapEnd": 15, "tyreAgeAtStart": 0 }],
"pitStops": [{ "lapNumber": 15, "pitLaneMs": 24500, "stationaryMs": null }] }] }
source is openf1 (recorded stints: OpenF1 from 2023, FastF1 for 2018–2022), derived (fallback when
a race has no recorded stints: rebuilt from accurate lap_times, so stints span first..last timed lap
and tyreAgeAtStart is null), or none. 2018 stints keep Pirelli’s named compounds (HYPERSOFT,
ULTRASOFT, SUPERSOFT, SUPERHARD alongside SOFT/MEDIUM/HARD). stationaryMs is only
available from the 2024 US GP onward; pre-2023 stops carry pitLaneMs only. Cached like other race routes (cacheControlForStatus).
GET /api/races/:id/strategy-insights?session=race|sprint
Analysis computed at read time from the session’s lap_times (or sprint_lap_times): no table of its own.
{ "degradation": [{ "team": { "...": "Team" }, "compound": "SOFT", "msPerLap": 104, "laps": 64, "stints": 4,
"points": [{ "tyreAge": 3, "lossMs": 508 }, { "tyreAge": 5, "lossMs": 440 }] }],
"pitBattles": [{ "attackerId": 4, "defenderId": 81, "attackerLap": 18, "defenderLap": 20,
"gapBeforeMs": 1400, "gapAfterMs": -2100, "outcome": "undercut" }] }
degradation is each team’s fuel-corrected time lost per lap of tyre age on each dry compound, softest first,
then the gentlest team. Stints are found as lap_number − tyre_life per driver and compound (stint_number
is missing for most seasons); lap_times already holds only green-flag laps, and laps over 107% of their
stint’s median are dropped. Each lap gets 55 ms × laps remaining taken off for fuel, then one least-squares
slope is fitted across the team’s stints, each with its own intercept. A stint needs 5 clean laps and a team
10 on a compound. points are the time lost to a new set in 3-lap buckets of tyre age.
pitBattles reads race_lap_traces, race_pit_stops and race_control_messages: two cars adjacent and
within 3 s at the end of the lap before the first stop, stopping 1–5 laps apart (no other stop by either in
between). The first to stop is the attacker; gaps are its time behind the defender (negative = ahead), on that
lap and on the second car’s out-lap, null once a car is lapped. outcome is undercut (attacker came out
ahead), overcut (defender did), held, or sc-assisted when a Safety Car, VSC or red flag ran on any lap from
the first stop to that out-lap. Drivers come as ids, like overtakes. About 9 KB per race in all.
GET /api/races/:id/race-story?session=race|sprint
Lap-by-lap story from full laps (2018+: OpenF1 for races ingested since Oct 2026, FastF1 before), drivers in finishing order:
{ "drivers": [{ "driver": { "...": "Driver" }, "finishPosition": 1,
"positions": [2, 1, 1], "gapsMs": [800, 0, 0], "intervalsMs": [800, null, null], "lapsDown": [0, 0, 0] }],
"battles": [{ "chaser": { "...": "Driver" }, "leader": { "...": "Driver" }, "lapStart": 12, "lapEnd": 19, "minGapMs": 310 }],
"weather": { "minuteOffsets": [0, 1], "airTempC": [25, 25.1], "trackTempC": [41.2, 40.8], "rainfall": [false, false] } }
Array index 0 is lap 1. gapsMs is null while a car is lapped (lapsDown > 0); intervalsMs is
null for the leader. A battle is 3+ consecutive laps within 1.0 s of the same car ahead. weather
is null when the session had no weather samples. About 40 KB per race before gzip.
GET /api/races/:id/telemetry?session=Q|SQ&a=CODE&b=CODE
Fastest-lap telemetry for a qualifying session (2018+: OpenF1 from 2023, FastF1 Q laps before). drivers lists everyone with a
stored lap (fastest first, no samples); laps holds full samples for only the two requested codes:
defaulting to the two fastest: to keep the payload (and Neon egress) small:
{ "session": "Q",
"drivers": [{ "driver": { "...": "Driver" }, "lapTimeMs": 79327 }],
"laps": [{ "driver": { "...": "Driver" }, "lapNumber": 11, "lapTimeMs": 79327,
"samples": { "distanceM": [0, 10], "timeMs": [0, 112], "speed": [321, 322], "throttle": [99, 100],
"brake": [0, 0], "gear": [8, 8], "x": [-1359, -1351], "y": [-498, -460] } }] }
All sample arrays share one 10 m distance grid, so two laps compare index by index.
GET /api/races/circuits
Returns a list of all circuits in the database, ordered alphabetically by name.
GET /api/races/circuit/:circuitKey
Returns { circuit, history, fastestLap, dominance, weatherStats, qualifyingImpact, safetyCarStats, outlinePath } for the circuit’s completed races, or 404 for an unknown key. history is the 10 most
recent races with their winner; each item includes hasSprint: boolean. dominance counts wins by
constructor and driver per era (all, modern, legacy, nineties).
outlinePath is an SVG path (1000×1000 viewBox) drawn from the x/y of the fastest stored qualifying lap
at the circuit’s latest race, or null before any telemetry exists (car data starts in 2018).
GET /api/races/circuit/:circuitKey/telemetry
Track character from one real lap: the circuit’s latest pole lap (falling back to that race’s fastest
stored qualifying lap when the pole sitter’s telemetry is missing: isPoleLap says which). Returns
{ raceId, year, raceName, driver, lapTimeMs, isPoleLap, profile, trace } or null when the circuit
has no telemetry (car data starts in 2018). profile (modules/circuits/track-profile.helpers.ts): full-throttle share (≥98%), longest flat-out run, top
speed, braking zones, and corners: every lift or brake, classed by apex speed (low < 130, medium
< 210 km/h). trace is speed/throttle/brake thinned to every 50 m.
Drivers
GET /api/drivers?year=N&team_id=T
| Param | Required | Default | Notes |
|---|---|---|---|
year | no | current year | |
team_id | no | all teams | Filter by team |
GET /api/drivers/standings?year=N
Returns driver championship standings for the year: [{ driver, stats }], ordered by championship
position, then championshipPoints.
Every driver stats object (here, /api/drivers/:id seasonStats, and each /career entry) carries
totalPoints (GP only), sprintTotalPoints (sprints only) and championshipPoints (their sum, what
the championship counts). All three are one-decimal strings, e.g. "300.0", "24.0", "324.0";
"0" when the driver has no stats row yet. Team stats carry the same three fields.
GET /api/drivers/racecraft?year=N
GP-session overtakes per driver from race_overtakes (2023+), ranked by net: [{ driver, made, suffered, net }]. Sprint passes are excluded. OpenF1 marks overtakes as possibly incomplete.
GET /api/drivers/:id/teammate-battle?year=N
Head-to-head against the team-mate with the most shared races that season (:id is the
season-scoped driver id): { teammate, sharedRaces, qualifying, race, points }, each a
{ driver, teammate } count. qualifying compares classified qualifying position; race only
counts races both drivers finished (Finished/Lapped/+N Lap(s), ADR 0002); points are GP
points. races lists every shared race in round order: { raceId, roundNumber, raceName, qualiGapMs, driver, teammate }, each side { qualiPosition, finishPosition, status, points }. qualiGapMs compares
lap times in the deepest session both reached (Q3, else Q2, else Q1); negative means the driver was
faster. medianQualiGapMs is the median of those gaps. year is accepted but ignored: the
driver’s own season sets the cache lifetime.
GET /api/drivers/:id?year=N
Returns { driver, seasonStats, recentResults } (the last 5 results) for the driver’s own season.
year is accepted but ignored: :id is season-scoped, so the row already pins the season.
GET /api/drivers/:id/career
Returns a driver’s stats across all seasons they have data in, newest first: [{ year, driverId, driverNumberThatYear, teamName, headshotUrl, stats }]. drivers rows are season-scoped and
FastF1’s names vary by season, so seasons are linked by person (common/identity.ts, golden cases in docs/identity-cases.json): the same
name ignoring accents and case, or the same code with one name extending the other (“Andrea Kimi
Antonelli” / “Kimi Antonelli”). “Jr.” still counts, so a father and son stay separate. /api/search
uses the same rule to list each person once, under their latest season.
Teams
GET /api/teams?year=N
Returns all teams for the season.
GET /api/teams/standings?year=N
Returns constructor championship standings for the year: [{ team, stats }], ordered by championship
position, then championshipPoints (GP + sprint; see driver standings for the three points fields).
GET /api/teams/pit-stops?year=N
Pit crews ranked by median stationary time (one botched stop can’t skew it): [{ team, stops, medianStationaryMs, fastestStationaryMs }]. Stops without a stationary time (pre-2024 US GP) are
ignored. Long-cached for past seasons (cacheControlForYear).
GET /api/teams/:id/pit-stops?year=N
Every timed grand prix stop by one team’s drivers (:id is season-scoped; year is accepted but
ignored, the team’s own season sets the cache lifetime): [{ raceId, roundNumber, raceName, driver, lapNumber, stationaryMs }] in round
and lap order. Sprint stops and stops without a stationary time are left out.
GET /api/teams/:id?year=N
Returns { team, seasonStats, drivers } for the team’s own season (year is accepted but ignored, as
for drivers).
GET /api/teams/:id/career
Returns a team’s stats across all seasons they have data in ([{ year, teamId, stats }], newest first), following the outfit through its
rebrands (constructorKey in common/identity.ts): RB’s career includes AlphaTauri and Toro Rosso,
but never its sister team Red Bull. Each entry keeps its own season’s teamId.
Predictions (Grand Prix)
GET /api/predictions/model-info
Returns the most recently computed model versions for GP and sprint predictions. Updates automatically whenever compute_features or compute_sprint_features runs: no deploy needed.
{
"data": {
"gpVersion": "weighted-v4",
"sprintVersion": "sprint-v3"
}
}
GET /api/predictions/upcoming
Returns the prediction for the next qualifying_done race with race_date >= today. Ordered ascending so the chronologically next race always wins: historical races stuck in qualifying_done from a partial backfill are excluded by the date guard.
{
"data": {
"race": { "id": 200, "name": "Monaco Grand Prix", "raceDate": "2026-06-07", "hasSprint": false, ... },
"predictedWinner": { "id": 42, "fullName": "Max Verstappen", ... },
"computedAt": "2026-06-06T22:00:00.000Z",
"modelVersion": "weighted-v4",
"featureInfo": [
{ "key": "grid", "label": "Grid Slot", "shortLabel": "Grid Slot", "importance": 20 },
{ "key": "qualiPace", "label": "Qualifying Pace", "shortLabel": "Quali Pace", "importance": 11 },
...
],
"drivers": [
{
"predictedPosition": 1,
"winProbability": "0.61200",
"podiumProbability": "0.88412",
"preQualiProbability": "0.32069",
"gridPosition": 1,
"driver": { "id": 42, "code": "VER", "fullName": "Max Verstappen", "team": { ... } },
"features": {
"grid": { "value": 0, "contribution": 1.70805 },
"qualiPace": { "value": 0, "contribution": 0.48767 },
"teamQualiPace": { "value": -0.2, "contribution": 0.48772 },
"driverPoints": { "value": 18, "contribution": 1.34037 },
"teammateEdge": { "value": 0.15, "contribution": 0.05717 },
"gridProcessional": { "value": 0, "contribution": 0.93347 },
"teamRacePace": { "value": -0.1, "contribution": 0.38514 }
}
}
]
}
}
features is GpFeatures: each of weighted-v4’s 7 features with its value (in the feature’s own
units) and contribution (its term in the driver’s log-odds score). A plain softmax (T = 1) of the
summed contributions over the field gives winProbability. Sprint predictions use the same shape
(SprintFeatures): value is the 0–1 Feature Score and contribution is weight × score / 0.3, so the
same softmax gives their probabilities too. featureInfo lists the model’s features in display order
with their label, a short label for tight spaces (the radar) and importance, the feature’s share of the
model in % (GP: of the fitted |weight per SD|; sprint: its hand weight), from common/feature-manifest.ts. gridPosition comes from the qualifying
sheet (sprint qualifying for sprint predictions), null when the driver has no row there.
GET /api/predictions/race/:raceId
Returns the prediction for a specific grand prix by race ID. Same shape as /upcoming. 404 when the race
has no prediction.
GET /api/predictions/title-odds?year=N
Latest Monte Carlo championship odds plus their per-round history (written by compute_title_odds):
{ "afterRound": 19,
"drivers": [{ "driver": { "...": "Driver" }, "titleProbability": 0.88, "expectedPoints": 452.3, "pointsP10": 420, "pointsP90": 475,
"finishes": [9, 4, 2] }],
"teams": [{ "team": { "...": "Team" }, "titleProbability": 0.81, "expectedPoints": 690, "pointsP10": 650, "pointsP90": 720 }],
"history": [{ "afterRound": 18, "driverId": 10, "titleProbability": 0.93 }] }
history has one entry per contender per completed round (2018–2026 replayed by
scripts/backfill_title_odds.py). finishes[i] counts the driver’s grand prix finishes in position i + 1
this season (sprints excluded): the countback the what-if uses to break a tie on points. 404 if no odds exist
for the season yet.
GET /api/predictions/pre-quali/upcoming
The forecast before qualifying (pre-quali-v1, ADR 0015) for the next race still before it: status
scheduled, sprint_qualifying_done or sprint_done, and race_date >= today. It’s written once the previous
race is ingested, from that race’s lineup and four features qualifying can’t set, so it stands all week. 404
NOT_FOUND (“No forecast before qualifying”) otherwise, e.g. before a season opener or after the finale. Cached
like any in-progress answer.
{
"data": {
"race": { "id": 290, "name": "Las Vegas Grand Prix", "raceDate": "2026-11-21", "status": "scheduled", ... },
"computedAt": "2026-11-12T14:20:00.000Z",
"modelVersion": "pre-quali-v1",
"drivers": [
{ "predictedPosition": 1, "winProbability": "0.32069", "driver": { "code": "VER", ... } },
{ "predictedPosition": 2, "winProbability": "0.22667", "driver": { "code": "ANT", ... } }
]
},
"error": null
}
Once qualifying is in, the GP prediction keeps it per driver as preQualiProbability (null for sprints and
drivers who weren’t in the forecast’s lineup), so the page can show how qualifying moved each chance.
GET /api/predictions/history?year=N
Returns all predictions for the year: both grand prix and sprint races merged and sorted by date descending. Includes actual results alongside predicted results for accuracy tracking.
Each item includes isSprint: boolean and the race’s circuit. The web links sprint items to /prediction/sprint/:id and main race items to /prediction/:id.
actualWinnerPredictedPosition is the grid slot the model had put the actual winner in: non-null
only once the race is decided; used by the frontend to show “model had them P4” on a missed call.
{
"data": [
{
"raceId": 210,
"raceName": "Canadian Grand Prix",
"raceDate": "2026-05-24",
"roundNumber": 5,
"isSprint": false,
"predictedWinner": { "code": "ANT", ... },
"actualWinner": { "code": "ANT", ... },
"correct": true,
"winProbability": "0.31200",
"actualWinnerPredictedPosition": 1,
"computedAt": "2026-05-23T20:00:00.000Z"
},
{
"raceId": 205,
"raceName": "Chinese Grand Prix",
"raceDate": "2026-03-15",
"roundNumber": 2,
"isSprint": true,
"predictedWinner": { "code": "ANT", ... },
"actualWinner": { "code": "RUS", ... },
"correct": false,
"winProbability": "0.29000",
"actualWinnerPredictedPosition": 3,
"computedAt": "2026-03-14T18:00:00.000Z"
}
]
}
GET /api/predictions/accuracy
Season-by-season accuracy breakdown, across every season with at least one decided race:
no year param; a single call returns the full history. Built from the same predicted/actual
comparison as /history, aggregated per year and split into gp/sprint/overall buckets.
A season with no decided races yet (e.g. it’s just started) is omitted entirely. accuracyPct
is null when a bucket has zero races (e.g. sprint for a season with no sprint weekends).
calibration grades the GP model’s whole field, not just its pick: every driver’s stored win
probability in every completed GP, against who won. It is null for a season with no scored GP.
bins: the probabilities in 10-point bands (fromtofrom+ 0.1), with how many drivers sat in each, how many of them won, and the sum of their probabilities (mean =probabilitySum / predictions).model,pole,uniform: average per race, lower is better. Brier is Σ over the field of (p − won)²; log loss is −ln p(winner), with p floored at 0.00001.uniformgives every driver 1/n.polegives the pole-sitterpoleWinRate(the share of all scored races won from pole) and splits the rest evenly.
{
"data": [
{
"year": 2026,
"gp": { "races": 12, "correct": 7, "accuracyPct": 58 },
"sprint": { "races": 5, "correct": 3, "accuracyPct": 60 },
"overall": { "races": 17, "correct": 10, "accuracyPct": 59 },
"calibration": {
"races": 12,
"poleWinRate": 0.4211,
"bins": [
{ "from": 0, "predictions": 205, "wins": 2, "probabilitySum": 4.1123 },
{ "from": 0.5, "predictions": 6, "wins": 4, "probabilitySum": 3.4512 }
],
"model": { "brier": 0.0712, "logLoss": 1.1514 },
"pole": { "brier": 0.0821, "logLoss": 1.6012 },
"uniform": { "brier": 0.95, "logLoss": 2.9957 }
}
},
{
"year": 2025,
"gp": { "races": 24, "correct": 13, "accuracyPct": 54 },
"sprint": { "races": 6, "correct": 3, "accuracyPct": 50 },
"overall": { "races": 30, "correct": 16, "accuracyPct": 53 },
"calibration": null
}
]
}
GET /api/predictions/standings?year=N
Returns the “Intelligence Standings”: driver rankings by average prediction score (rawWeightedScore, winProbability, overallScore; no per-feature breakdown). Each row includes sprint aggregates (sprintWins, sprintPodiums, sprintTotalPoints) and championshipPoints (GP + sprint season points).
Sprint Predictions
GET /api/sprint/upcoming
Returns the sprint prediction for the next sprint weekend whose status is sprint_qualifying_done,
sprint_done or qualifying_done and whose sprint_date is today or later; 404 when there is none. Same
envelope as the grand prix upcoming prediction, with modelVersion: "sprint-v3": the same seven features and
featureInfo as the GP model, scored on the sprint grid (ADR 0014). podiumProbability is always null.
GET /api/sprint/race/:raceId
The sprint prediction for that race weekend: same envelope as /api/sprint/upcoming. 404 when the
weekend has no sprint prediction.
GET /api/sprint/race/:raceId/detail
Everything the sprint page needs: { race, prediction, results, laps }, prediction is null
before sprint qualifying, results/laps are empty until the sprint has run. 404 for a
conventional (non-sprint) weekend.
{
"data": {
"race": { "id": 205, "name": "Chinese Grand Prix", "hasSprint": true, "sprintDate": "2026-03-15", ... },
"prediction": {
"predictedWinner": { "code": "ANT", ... },
"modelVersion": "sprint-v3",
"featureInfo": [{ "key": "grid", "label": "Grid Slot", "shortLabel": "Grid Slot", "importance": 20 }, ...],
"drivers": [
{
"predictedPosition": 1,
"winProbability": "0.29000",
"podiumProbability": null,
"gridPosition": 1,
"driver": { ... },
"features": {
"grid": { "value": 0, "contribution": 1.70805 },
"qualiPace": { "value": 0, "contribution": 0.41112 },
"...": "one per GP feature: the same seven keys as /api/predictions"
}
}
]
},
"results": [ ... ],
"laps": [ ... ]
}
}
Search
GET /api/search
Returns all unique drivers (their latest profiles), teams, and circuits across all seasons for autocomplete search.
{
"data": {
"drivers": [
{
"id": 420,
"seasonId": 27,
"teamId": 10,
"driverNumber": 1,
"code": "VER",
"firstName": "Max",
"lastName": "Verstappen",
"fullName": "Max Verstappen",
"nationality": "Dutch",
"headshotUrl": "https://...",
"team": {
"id": 10,
"seasonId": 27,
"teamKey": "red_bull",
"name": "Red Bull Racing",
"nationality": "Austrian"
}
}
],
"teams": [
{
"id": 10,
"seasonId": 27,
"teamKey": "red_bull",
"name": "Red Bull Racing",
"nationality": "Austrian"
}
],
"circuits": [
{
"id": 1,
"circuitKey": "albert_park",
"name": "Albert Park Circuit",
"country": "Australia",
"city": "Melbourne",
"lapCount": 58,
"trackLengthKm": "5.278",
"overtakeRate": "0.320",
"numberOfCorners": 14,
"drsZones": 4,
"scProbability": "0.600",
"imageUrl": null
}
]
}
}
History (F1DB)
All-time data imported from F1DB (CC-BY-4.0). Cached for a day.
GET /api/history/records
Top-10 leaders { f1dbId, name, value, nationality, coreId, active } for drivers (wins, championships,
poles, podiums, starts) and constructors (wins, championships, poles). nationality is
an F1DB country id. coreId is the core driver/team id for the page link (null before 1980, when core
data starts): a driver’s latest season, and for a constructor its current core key or else its
longest-running one. active is true only for the latest season’s grid.
Ties sort by wins, then name. Also:
rates: top-10winRate/poleRate/podiumRate(valueis a 0–1 ratio), only drivers with at leastrateMinStarts(50) starts.chases: per driver stat, therecordholder and the best activechaserwho doesn’t hold it (null when no active driver has scored).
GET /api/history/milestones
Five drivers each for youngestWinner, youngestPole, youngestPodium, youngestStarter,
oldestFirstWin and longestWaitForWin (debut to first win): { f1dbId, name, nationality, coreId, active, days, raceName }.
GET /api/history/lineages
Constructors that raced under more than one name (F1DB chronology), one family per team keyed by
its latest name: { f1dbId, name, coreTeam: { id, teamKey } | null, active, members: [{ f1dbId, name, yearFrom, yearTo, raceWins, championships, coreId }] }. Member totals are per constructor, so a name that
recurs (Renault, Sauber) repeats them. Active families first.
GET /api/history/on-this-day?date=MM-DD
{ requested, date, races }: up to 10 completed races (core DB, 1980+) held on that calendar
day, newest first, with the winner. When the day has none, date is the nearest day that does.
date is required: missing or not a real day → 400 INVALID_DATE.
GET /api/drivers/:id/history
The core driver’s all-time F1DB record (career totals, first race / podium / pole / win), matched by normalised full name. 404 if the driver isn’t in the imported release.
GET /api/teams/:id/history
The constructor’s all-time totals plus chassis and engine per season, matched via
f1dbConstructorId(team_key). 404 if unmatched.
GET /api/races/:id/recap
Home-hub summary: { winner, predictedWinner, predictionHit, fastestStop: { driver, stationaryMs }, topBattle }: the longest race battle. Each part is null when its data doesn’t exist. Cached by race status
like the other race routes (30 s while there is no winner).
Data Quality
GET /api/quality?year=N
Returns the latest data-quality audit report for a season (records produced by the
data_quality_audit data-engine job). 404 when no report exists for the year yet. Dev only: 404 in production.
{
"data": {
"year": 2026,
"generatedAt": "2026-08-24T12:00:00.000Z",
"healthScore": "91.00",
"racesAudited": 13,
"issueCount": 7,
"fixableCount": 3,
"bySeverity": { "high": 2, "medium": 3, "low": 2 },
"byTable": { "fp2_long_run_times": 2, "lap_times": 3 },
"issues": [
{
"raceId": 420,
"roundNumber": 13,
"year": 2026,
"tableName": "fp2_long_run_times",
"checkName": "driver_coverage",
"severity": "high",
"detail": "FP2 coverage 0.00% (0/~20 drivers)",
"fixable": true,
"isSprint": false
}
]
}
}
Error Codes
| Code | HTTP | Meaning |
|---|---|---|
NOT_FOUND | 404 | Route, race, driver, team, circuit or report doesn’t exist |
INVALID_ID | 400 | :id / :raceId isn’t a number |
INVALID_YEAR | 400 | year isn’t a 4-digit number |
INVALID_SESSION | 400 | session isn’t race/sprint (or Q/SQ for telemetry) |
INVALID_DATE | 400 | date isn’t a real MM-DD day |
DB_ERROR | 503 | Database unreachable (/api/health/db) |
INTERNAL_ERROR | 500 | Unhandled server error |