{ "openapi": "3.1.0", "info": { "title": "Live Tennis API", "version": "1.13.60", "contact": { "name": "Live Tennis API", "url": "https://livetennisapi.com" }, "license": { "name": "MIT", "url": "https://gitlab.com/livetennisapi/openapi/-/blob/main/LICENSE" }, "termsOfService": "https://livetennisapi.com/terms", "description": "Real-time tennis scores, player data, match-winner market prices, and\nmodel-driven match analysis. Read-only. Coverage spans ATP, WTA,\nChallenger, ITF and the junior Grand Slam draws — depth differs by tour\nand surface; `GET /history/coverage` states the measured numbers.\n\nAccess is tiered (FREE / BASIC / PRO / ULTRA). Each tier includes\neverything in the tiers below it; the concrete deltas are:\n\n`FREE` — self-serve, no card (https://livetennisapi.com/subscribe/free).\nLive and upcoming matches, current scores, players, fixtures, the\ntournament catalogue (`/tournaments`), and your own usage stats.\n30 requests/minute, 100/day. No market prices, no model fields, no\nWebSocket. Historical results are not part of the tier, but a FREE key\nmay spend 20 calls per calendar month on the history endpoints as a\ntaste of the product — served exactly like an entitled call. Past that\nthey answer `403 upgrade_required` carrying\n`free_history_taste: \"used\"`.\n\n`BASIC` — adds historical data: the completed-match listing\n(`/history/matches`, and `status=completed` on `/matches`), the\nper-match point-by-point tape with the model win-probability on the\nrows where the model ran\n(`/history/matches/{matchId}`), the measured completeness rollup\n(`/history/coverage`), and the results archive (1968–2022) —\ndeep results (`/history/archive/matches`), archive player bios\n(`/history/archive/players`), career aggregates\n(`/history/archive/career`) and head-to-head (`/h2h`).\n60 requests/minute, 1,000/day.\n\n`PRO` — adds match events (`/matches/{matchId}/events`), market prices\n(`/markets`, `/markets/{matchId}/prices`, `/matches/{matchId}/prices`),\nthe pre-built monthly bulk history packages (`/history/packages`) and the\nrank-ordered rankings listing (`/rankings?system=`).\n300 requests/minute, 10,000/day.\n\n`ULTRA` — adds model analysis (`/matches/{matchId}/analysis`), the live\nmodel fields (`win_probability_p1`, `danger`) on every score object,\nin-play match statistics (`/matches/{matchId}/statistics`), per-player\nas-of ranking records (`/rankings?player=`), the as-of Elo tape\n(`/rankings?system=elo` — both modes, plus `kind=elo` bulk packages),\nrally construction\n(`/rally/matches`, shot-by-shot charted data), career and per-match\ncharting stats (`/charting/players`, `/charting/matches/{chartingMatchId}`),\nthe reconstructed 2013–2022 archive tape\n(`/history/archive/matches/{archiveId}/tape` — also opened by ANY active\nHistory plan, Starter included), the WebSocket live feed at `/ws` and the\nhigh-fan-out push feed (`/ws-token`), and outbound webhooks (direct keys).\n600 requests/minute, 500,000/day.\n\nHistory runs in two continuous halves, deliberately non-overlapping: the\npoint-by-point tape (2023→now) covers January 2023 to now, match by\nmatch, point by point; the results archive (1968–2022) covers 1968\nthrough 2022 as winner/loser-shaped RESULTS (final score, seeds, ranks at\nthe time — no point-by-point). The archive ends exactly where the tape\nbegins, so no match is ever served from two datasets.\n\nArchive results played **2013–2022** additionally carry a RECONSTRUCTED\npoint-by-point tape at `/history/archive/matches/{archiveId}/tape` — the\nscore sequence behind the published result, rebuilt from the public record\nafter the fact. 97,901 matches / 14,340,663 rows, seasons **2013–2022\nONLY**: the archive holds a further 977,903 results from 1968–2012 and NOT\nONE of them has a tape, because there is no public point-by-point record of\nthose years to rebuild and we do not manufacture one. Write the range as\n2013–2022, never as \"pre-2023\" — the second phrasing reads as 1968 onward\nand is wrong by 45 seasons.\n\nNobody watched those matches, and the data says so: `timestamp`,\n`win_probability_p1` and `danger` are null on EVERY row and cannot be\nfilled in later — the production table has no timestamp column at all, and\nthe promotion script refuses to run if one ever appears.\nContrast the 2023→now tape, which is our own recording: the rows we\nactually watched carry a real clock, and most of them a model probability.\nCoverage of the era is real but partial — 19.3% of archive matches played\n2013–2022 and 44.9% of tour-level play; main-draw tour buckets run\n91.6–98.7%, ATP Challenger main draws 55.3% and Challenger qualifying\n33.6%, slam QUALIFYING only 16.0% (ATP) / 18.1% (WTA), and ITF/futures\neffectively nothing (25 of 116,575 ATP futures matches). It is not a\ncomplete record of the era and is not sold as one.\n\nTwo different gates, on purpose: the per-match tape needs core ULTRA **or\nany active History plan, Starter included**; the per-year bulk files\n(`/history/packages?kind=archive_tape`, 2013–2022, JSONL + CSV) need core\nULTRA **or** a History Pro/Business subscription (an active one-off package\nwindow counts). Core PRO carries NEITHER — it reads the archive RESULT and\nis refused the tape.\n\nA call above your tier returns `403 {\"error\":\"upgrade_required\"}` — never\na silent empty result.\n\nCORS is enabled across the REST surface: every response carries\n`Access-Control-Allow-Origin: *` (GET/OPTIONS, no credentials mode — there\nis no cookie or session, and a wildcard origin is incompatible with\ncredentials by design). Putting a FREE key in browser code is acceptable —\nit is capped and revocable; a paid key belongs server-side only.\n\nThe `/history/*` endpoints are also sold standalone as the **Historical\nData API** (no live-API subscription required): **Starter** — single-match\npoint-by-point tape reads via the API (tape plus the model win-probability\nper point), all tours (ATP/WTA/Challenger/ITF/juniors), one match per\nrequest, no bulk downloads; **Pro** — everything in Starter plus bulk\nmonthly package\ndownloads and higher rate limits; **Business** — everything in Pro plus\nyear-scale archive exports, top rate limits and priority support. One-off\n1-month and 1-year access passes are available without a subscription.\nThe results archive (1968–2022) endpoints (`/history/archive/*`, `/h2h`)\nride with the same entitlement — any active History plan, Starter\nincluded, opens them alongside the tape endpoints, and that includes the\nreconstructed 2013–2022 archive tape. The per-year `archive_tape` bulk\nfiles do not: those need Pro, Business or an active one-off package pass,\nbecause a Starter grant reads tapes one at a time and does not download\nyears of them.\nPlans and prices: https://livetennisapi.com/historical-tennis-data-api\n\nAll timestamps are UTC ISO 8601 with a `Z` suffix. List endpoints return\n`{data, meta}`; single resources return the object directly. Ignore\nunknown fields — additive changes land within v1.\n\nA native WebSocket live feed (ULTRA) exists at `/ws` under the same base\nURL. Subscribe with one JSON frame whose keys are `topics` and\n(optionally) `signals`: `{\"topics\":[\"live-scores\"]}` — `topics` may also\nname `\"match:\"`. The server acks with a `subscribed` frame, then\npushes `score` frames on every change plus a `ping` heartbeat roughly\nevery 15s. Score frames carry the ULTRA model fields\n(`win_probability_p1`, `danger`) live; a null there means the model had\nno output for that point, not that the field is REST-only. Opt into extra\nsignals with `{\"topics\":[\"live-scores\"],\"signals\":[\"break_point\"]}` to\nalso receive `break_point` and `break_point_result` frames — and\n`signals:[\"stoppages\"]` (2026-09-12) for the stoppage family: medical\ntimeouts, trainer calls, toilet breaks, whole-match stops and clock-inferred\npauses, each an Event object plus `match_id` — (schemas\n`BreakPoint` / `BreakPointResult`). Without `signals`, score frames only.\n\n`signals` may also name `points` — the live per-point event stream: one\n`point` frame (schema `PointFrame`) per persisted point of your\nsubscribed matches. On the live basis `seq` is ARRIVAL order, not match\norder: use it to page, dedup and resume, and sort by\n`(set, game, number)` to replay in playing order — a tuple that may\nrepeat or carry a null `number`, so it orders points without identifying\nthem (see `GET /matches/{matchId}/points`). The signal is\nconfig-gated and ships OFF by default; the `subscribed` ack echoes the\nsignals actually active, so `points` present in the ack means point\nframes will flow and missing means they will not. Frames arrive only for\nmatches with `pbp_coverage: \"point\"` — a `game`-coverage match sends\nnone, honestly. Best-effort with NO replay: on reconnect (or to join\nmid-match) catch up via `GET /matches/{matchId}/points?after_seq=` and\ndedup by `seq`.\n\nMax 2 concurrent connections per key. For high fan-out, `GET /ws-token`\nmints a token for the separate push feed.\n\nCLOSE CODES. Every refusal sends its `error` frame **and then closes with a\ncode that says what to do next**, so a reconnect loop or a supervisor keyed\non the close code alone behaves correctly without parsing the frame. The\nclose *reason* repeats the frame's `error` string, so `(code, reason)` is a\ncomplete diagnosis even if the frame was missed.\n`1013` Try Again Later — transient, the request was fine: `connection_limit`\n(reason `connection_limit:per_key` or `connection_limit:server`) and\n`service_unavailable`. Back off and retry; for `per_key` release a\nconnection first, or move to the push feed, which has no shared ceiling.\n`1008` Policy Violation — the request as sent will never be accepted:\n`unauthorized`, `upgrade_required`, `email_unverified`, `client_blocked`,\n`bad_json`, `no_topics`, and any mid-stream loss of access. Fix the request\nor the credentials; do not retry unchanged.\n`1012` Service Restart — reconnect with backoff and re-subscribe.\n`1000` Normal Closure — you closed it, or the stream ended normally.\nChanged 2026-09-18: refusals raised during the *handshake* previously closed\n`1000` with an empty reason, indistinguishable from an orderly shutdown, so\na client awaiting its `subscribed` ack saw only a normal close. The error\nframe was, and still is, delivered before the close; only the close code and\nreason changed.\n\nGetting a match id: it is the `id` field on any match object returned by\n`GET /matches`, `GET /fixtures` or `GET /history/matches`, and the same value\nworks on every route that takes `matchId`.\n" }, "servers": [ { "url": "https://api.livetennisapi.com/api/public/v1" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "paths": { "/health": { "get": { "summary": "Liveness probe (no auth)", "operationId": "healthCheck", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "version": { "type": "string", "const": "v1" } } } } } } } } }, "/matches": { "get": { "summary": "List matches by lifecycle status (FREE)", "description": "`status=live` and `status=upcoming` are the FREE current-state picture. `status=completed` pages historical results and is part of the paid History product — it requires BASIC (the same rule as `/history/matches`). A FREE key may spend its 20 free history calls per calendar month here; past that the answer is `403 upgrade_required` carrying `free_history_taste: \"used\"`. The `player`, `country`, `from`/`to`, `tour`, `draw`, `has_analysis` and `has_market` filters are optional, AND-composed, applied inside the query (before pagination), and work on every status — omitting them returns exactly what the endpoint returned before they existed. `has_analysis` and `has_market` are the two availability flags every row already carries: filter the slate with them and call `/matches/{matchId}/analysis` and `/matches/{matchId}/prices` only for the ids that have something, rather than probing per match for a 404.", "operationId": "listMatches", "parameters": [ { "name": "status", "in": "query", "description": "`live` (default) and `upcoming` are the FREE current-state picture. `completed` and `cancelled` are terminal LISTINGS, part of the history product (BASIC, or any History plan on a free key; a FREE key's 20 free history calls each month are served here too). `cancelled` covers feed-cancelled, walkover-with-no-stated-winner and postponed-never-played matches; a walkover that named its winner is `completed`. `cancelled` pages with `limit`/`offset` (optionally `from`/`to`) and does NOT accept `updated_since` (400 `bad_request`). Any other value is a 400 `bad_status` carrying the accepted list in `allowed`.", "schema": { "type": "string", "enum": [ "live", "upcoming", "completed", "cancelled" ], "default": "live" } }, { "$ref": "#/components/parameters/tour" }, { "$ref": "#/components/parameters/draw" }, { "$ref": "#/components/parameters/player" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/tournamentId" }, { "$ref": "#/components/parameters/tier" }, { "$ref": "#/components/parameters/hasAnalysis" }, { "$ref": "#/components/parameters/hasMarket" }, { "$ref": "#/components/parameters/isQualifying" }, { "$ref": "#/components/parameters/gender" }, { "$ref": "#/components/parameters/playedFrom" }, { "$ref": "#/components/parameters/playedTo" }, { "$ref": "#/components/parameters/updatedSince" }, { "$ref": "#/components/parameters/withdrawnSince" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Matches with latest score", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Match" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}": { "get": { "summary": "Full match detail (FREE; +market PRO, +analysis ULTRA)", "operationId": "getMatch", "parameters": [ { "$ref": "#/components/parameters/matchId" } ], "responses": { "200": { "description": "Match with score; `market` embed at PRO+, `analysis` embed at ULTRA", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/score": { "get": { "summary": "Current score only — lowest-latency REST read (FREE)", "description": "This is a POINT-IN-TIME SNAPSHOT: the single current state, overwritten on every score commit. It carries no history and no accumulated statistics. For the SEQUENCE of states — who served each game, hold/break, every score state in forward order — use `/history/matches/{matchId}?sequence=clean`, which works on a LIVE match, not only a completed one. For in-play statistics use `/matches/{matchId}/statistics` (ULTRA); they are deliberately not on this object, because they can be further behind the match than the score and must carry their own `as_of`. ARCHIVED FINALS (since 2026-09-20). The live-score rows behind this read are retired by a 90-day retention sweep, and a match recovered from an official day list may never have had one. When there is no live row at all, a SETTLED match — `outcome` non-null on the match object: completed, retired, walkover, default, abandoned, unresolved — is answered from its archived final: the same read `GET /matches?status=completed` already embeds, through the same serializer, so the listing and this endpoint can never disagree about whether a score exists. A live tape always outranks the archive — the fallback is reached only when no publishable live row exists, so a live match reads exactly what it did before. An archived final carries `age_seconds: null`, `observed_age_seconds: null`, `sources_count: null` and `accepted_at: null` — no clock is claimed for a state nobody watched — and `timestamp` is null where the archived row has none (a reconstructed final). The Score object carries no data-source label; whether that final was observed or reconstructed is what `GET /history/matches/{matchId}` reports once, in `meta.point_source`. 404 is kept for: an upcoming match with no row (nothing to serve yet), a cancelled match that was never played (nothing settled), and a settled match with nothing recorded anywhere — the fallback serves a final that exists, it never invents one. WITHDRAWN STATES (since 2026-09-23). When the legality gate behind this read refuses a state a stream has already published, the `verdict` object on the score says so: `kind`, `superseded_sequence`, `reason` and `safe_to_resume`. It is null on an ordinary read. The push feed, the WebSocket and webhooks carry the same judgement as a `score_withdrawn` frame naming the same sequence, so a stream consumer learns a state was taken back without polling. `GET /history/incidents` is the published register of data-quality incidents. THE RECOVERY PATH (since 2026-09-25). A consumer that missed the frame cannot get the live `verdict` back, because it is recomputed over the newest state and returns null as soon as the next state is accepted. Every withdrawal is now recorded durably when the judgement is made: pass `?sequence=N` here to have `verdict` answer for the sequence you hold, and read `GET /matches/{matchId}/withdrawals` for the whole record on a match, including the frame exactly as the feed sent it. Before 2026-09-20 every settled match older than the retention window answered 404 here (13,437 completed matches from the previous 180 days, 157,170 all time, measured at the change) while the completed listing served its score.", "operationId": "getMatchScore", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "$ref": "#/components/parameters/sequence" } ], "responses": { "200": { "description": "Current score (ULTRA adds win_probability_p1 + danger). On a settled match with no live row, the archived final (since 2026-09-20) — `age_seconds`, `observed_age_seconds`, `sources_count` and `accepted_at` null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Score" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No such match; an upcoming match with no score yet; a cancelled match that was never played; or a settled match with nothing recorded anywhere — no live row and no archived final. Since 2026-09-20 a settled match whose live rows were retired by the 90-day sweep is NOT a 404: it answers 200 with its archived final (`age_seconds: null`), the same score `GET /matches?status=completed` embeds for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/events": { "get": { "summary": "Match events, newest first (PRO)", "operationId": "listMatchEvents", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/events": { "get": { "summary": "Slate-wide events feed — every match's events in one call, oldest first, cursor by id (PRO)", "operationId": "listSlateEvents", "description": "Added 2026-09-13. The rows of GET /matches/{matchId}/events for EVERY match in one request, so a poller watching the whole live slate spends one request per tick rather than one per match. `after_id` returns rows with id greater than the one passed, ascending, and `meta.next_cursor` names the last id served (null on a short page = caught up); `since` (UTC instant) is the first-call lower bound; with neither the newest page is served, still ascending. `type` narrows to a comma-separated list of event types or the family name `stoppages` (stoppage_*, pause_*, medical_timeout_*, trainer_called*, toilet_break_*). Rows carry `id` and `match_id` next to the per-match fields. Measured 2026-09-13: a scorer-stated stoppage reaches the feed a median 8 s (p90 13 s) after the scorer's own instant; the WebSocket `stoppages` signal pushes the same row as it is written.", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated event types (see Event.type), or `stoppages` for the whole stoppage family.", "example": "medical_timeout_start" }, { "name": "after_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Serve rows with `id` greater than this, ascending. Take it from `meta.next_cursor` or the last row's `id`." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "First-call lower bound, a UTC instant. Rows stamped after it, ascending.", "example": "2026-09-13T09:00:00Z" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Events across the slate, ascending id", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SlateEvent" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "description": "bad_type, bad_after_id or bad_since" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/players/{playerId}/stoppages": { "get": { "summary": "One player's in-match stoppages and did-not-finish outcomes, newest first over a window (PRO)", "description": "Added 2026-09-16. Medical timeouts and trainer calls on the player's matches (from the stoppage family of GET /matches/{matchId}/events), plus retirements and walkovers where THIS player is the non-winner, merged and sorted by `at` descending. Window: `since`/`until` (ISO date or UTC instant; default the last 180 days; at most 366 days, else 400 window_too_long). `kind` filters the seven row kinds (default medical_timeout,trainer_called,retirement,walkover); `before` pages by `meta.next_cursor`. `meta.latest_medical_timeout` and `previous_medical_timeout` are the two newest medical timeouts in the window whatever the page or the kind filter. `meta.record_starts` states how far back each family goes: stoppage rows exist from 2026-09-12 only; outcome rows from the oldest match with a stated winner. In-match stoppages and match outcomes only — no off-court injury record exists here. Same PRO capability as /events. `GET /players/{playerId}/injuries` serves the identical response.", "operationId": "listPlayerStoppages", "parameters": [ { "name": "playerId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start — an ISO date (start of that day) or a UTC instant. Default `until` minus 180 days.", "example": "2026-03-19" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end — an ISO date (the whole of that day) or a UTC instant. Default now.", "example": "2026-09-15T00:00:00Z" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated row kinds from medical_timeout, trainer_called, toilet_break, pause, stoppage, retirement, walkover. Default `medical_timeout,trainer_called,retirement,walkover`.", "example": "medical_timeout,retirement" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `meta.next_cursor` of the previous page (opaque `:`), valid for the same window and kinds." }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "The player's stoppage and outcome rows, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerStoppage" } }, "meta": { "$ref": "#/components/schemas/PlayerStoppagesMeta" } } } } } }, "400": { "description": "window_too_long, bad_window, bad_since, bad_until, bad_kind or bad_cursor" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "description": "No roster player holds this id. Carries the archive signpost (`detail` + `see`) when the id is a corpus person id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerNotFound" } } } }, "410": { "$ref": "#/components/responses/PlayerGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/players/{playerId}/injuries": { "get": { "summary": "Alias of /players/{playerId}/stoppages — the identical response (PRO)", "description": "Added 2026-09-16. The same handler, parameters, rows and meta as /players/{playerId}/stoppages, under the word the request used. The honest name is `stoppages`: nothing here is a diagnosis, only what the scorer, umpire or result stated.", "operationId": "listPlayerInjuries", "parameters": [ { "name": "playerId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Identical to /players/{playerId}/stoppages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerStoppage" } }, "meta": { "$ref": "#/components/schemas/PlayerStoppagesMeta" } } } } } }, "400": { "description": "window_too_long, bad_window, bad_since, bad_until, bad_kind or bad_cursor" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "description": "No roster player holds this id. Carries the archive signpost (`detail` + `see`) when the id is a corpus person id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerNotFound" } } } }, "410": { "$ref": "#/components/responses/PlayerGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/status-history": { "get": { "summary": "The per-match status ledger — every status / event_status transition with its UTC instant (BASIC, history)", "description": "Added 2026-09-12. Append-only, oldest first: one row per change of `status` and/or `event_status`, with the instant we published it, the value before and the effective value after, the derived `outcome`, and the newest score row at that instant. A correction is a new row, never an edit — a close published as `unresolved` and later confirmed shows the flip to `completed`; a completion that reopened shows `completed -> live`. `basis: observed` rows exist from 2026-09-11T22:45:48Z; `basis: backfill` rows (2026-09-12) were reconstructed from the one stamp per kind the match row kept before the ledger existed (last promotion to live from 2026-09-05, completion instant from 2026-08-21, last reopen, last event_status change) — one row per stamp, overwritten intermediate transitions are not recovered. A correction to a PUBLISHED result — `status`, `event_status`, winner or the final score changing after the match was first published as completed — is a new row with `basis: restatement` (from 2026-09-22), never a silent edit; `result_restated_at` / `result_version` on the match summarise them and `GET /history/matches?restated_since=` finds them. History capability (BASIC and the Historical Data plans), like the tape.", "operationId": "getMatchStatusHistory", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Status transitions, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusChange" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/withdrawals": { "get": { "summary": "The durable record of every score state we withdrew on this match (ULTRA)", "description": "Added 2026-09-25. One row per refused `sequence`, oldest first, each carrying the `score_withdrawn` frame exactly as the push feed sent it.\n\nThis is the RECOVERY PATH for a missed frame. The `verdict` object on `GET /matches/{matchId}/score` is recomputed on every read over the newest state, so it returns null again as soon as the next state is accepted, which in a live match is seconds. The record here is written when the judgement is made, before the frame is delivered, so a consumer that was disconnected can still learn that a sequence it holds was taken back. `GET /matches?withdrawn_since=` says which matches to ask about; `?sequence=N` on the score read answers for one sequence without fetching the list.\n\nULTRA, the tier that receives the frame on the push feed and the native WebSocket. An empty `data` is the ordinary answer and means nothing was withdrawn on that match. Records are kept 90 days from the withdrawal.", "operationId": "getMatchWithdrawals", "parameters": [ { "$ref": "#/components/parameters/matchId" } ], "responses": { "200": { "description": "Withdrawals on this match, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "match_id": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreWithdrawal" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/analysis": { "get": { "summary": "Model analysis for a match (ULTRA)", "description": "The model's thesis and profile for one match.\n\nCOVERAGE IS NOT UNIVERSAL, and a polling client should plan for that. Analysis is produced per match by the model pipeline rather than emitted for every fixture: over the seven days to 2026-08-27, 1,225 of 2,863 matches that went live or completed carried one (42.8%). A match that has none yet returns `404 {\"error\":\"no_analysis\"}` (since 2026-09-02; before that the body was a bare `not_found`) — that is the documented absence, not a fault, and it can turn into a 200 later in the same match once the pipeline has run. Never treat this 404 as a reason to retry harder. The body names which absence it is: `not_found` is an id that does not exist; `no_analysis` carries `match_id` and `coverage: \"none\"` for a real match with nothing computed.\n\nFILTER THE SLATE FIRST. Every row of `GET /matches` and the detail carries `has_analysis` (every tier), the same fact this endpoint answers 404 about — read it there and call only the matches that carry one, instead of spending one 404 per match.\n\nONE CALL INSTEAD OF THREE. `GET /matches/{matchId}` carries the same thesis and profile in its `analysis` key on ULTRA, alongside `market` and `market_price` on PRO and above, next to the live score. It answers `200` whether or not analysis and a market exist — the keys are `null` instead — so a per-match poll built on the detail route replaces the score, analysis and prices calls with one request and never spends a call on a 404.", "operationId": "getMatchAnalysis", "parameters": [ { "$ref": "#/components/parameters/matchId" } ], "responses": { "200": { "description": "Thesis + profile (either may be null)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analysis" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "description": "`error: not_found` — no such match id. `error: no_analysis` (with `match_id`, `coverage: \"none\"`, `detail`) — the match exists and nothing has been computed for it; `has_analysis` on the match list says so without a probe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/statistics": { "get": { "summary": "In-play statistics — aces, double faults, serve split, hold/break %, break points, service & return points (ULTRA)", "description": "In-play statistics for one match, in TWO families that are deliberately not merged.\n\nDERIVED (the top level of `players.pN`) are rebuilt from the point-by-point record: service and return games played and won, hold and break percentage, break points faced, saved and converted, service and return points.\n\nMEASURED (`players.pN.measured`) are counted upstream, so they include what no point record can yield — ACES AND DOUBLE FAULTS, the first- and second-serve split, winners and unforced errors. Both families name some of the same quantities, computed two entirely different ways; that is a cross-check, not a duplication to collapse.\n\nMeasured coverage is not uniform and every measured field is optional — an absent field is OMITTED, never zero-filled, so read the keys you are given. Aces and double faults are present across every tour. The serve split and break points saved are present on the main tours and absent on ITF singles. Winners and unforced errors historically appeared on a minority of main-tour matches and have not been delivered upstream since 2026-07-12 (measured 2026-08-17).\n\n`freshness.derived` and `freshness.measured` each carry their own `coverage` (`live` | `final` | `stale` | `none` | `diverged`; `final` = the closing figures of a completed match — a finished match cannot be \"stale\", so its `age_seconds` is null), `as_of`, `age_seconds` and `describes` — the match state the numbers describe. On `diverged` the measured VALUES are withheld and `freshness.measured_divergence` says why; the top-level `coverage` only summarises the response. `none` on both returns 200 with null players, not 404 — the match exists and holding nothing for it is the honest answer.\n\nTHE TWO AGES USE DIFFERENT CLOCKS AND MUST NOT BE COMPARED. The derived age is measured against the newest SCORE row, because between points there is no new score either and wall-clock age would report staleness that does not exist. The measured age is wall clock, because those are fetched on a fixed cadence.\n\nTiebreak games are excluded from the DERIVED family and counted separately; the live record collapses a whole tiebreak onto one entry, so most of its points are lost.", "operationId": "getMatchStatistics", "parameters": [ { "$ref": "#/components/parameters/matchId" } ], "responses": { "200": { "description": "Statistics with their own coverage and as_of", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchStatistics" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/points": { "get": { "summary": "Live per-point events in seq order — the REST catch-up for the WebSocket point stream (ULTRA)", "description": "The live per-point event stream of one match, in `seq` order. The WebSocket `point` frames are best-effort with NO replay, so this endpoint is how you join mid-match and how you recover a dropped connection: subscribe the WS first, then GET with `after_seq` set to the last seq you hold, then dedup everything by `seq` — it is per-match, monotonic and never skips a value, so it is the whole reconciliation key.\n\n`seq` IS ARRIVAL ORDER, NOT MATCH ORDER, ON THE LIVE BASIS. It is assigned in the order points are committed, and a live match is fed by more than one upstream at different speeds, so a point from a set that has just ended can be committed AFTER points from the set that follows it and carry the higher `seq`. Each row is self-consistent — its `set`, `game`, `number`, `score`, `sets` and `games` all describe the point that was played — but reading the tape in `seq` order can show the set or game counter step backwards. Measured over a recent seven-day window this affected a minority of live matches, and never the `reconstruction` basis. So `seq` is the right key for paging, dedup and resume (unique, stable, strictly increasing — all `after_seq` needs) and the wrong key for chronology: sort by `(set, game, number)` to replay in playing order. That tuple ORDERS points; it does not IDENTIFY them. `number` is null wherever we joined a game already in progress, and the same tuple can appear on more than one row — a game re-expanded by a second source re-asserts ordinals it already holds, which on the live basis is a normal re-statement rather than a correction. There is no revision id, superseded-seq or correction flag: rows are append-only and never rewritten, so `after_seq` never needs a refetch, and the page-level `quality` field reads `revised` when the page contains such a re-statement. On the `reconstruction` basis of a completed match, `seq` is contiguous 1..N in true match order and the two agree.\n\nREAD THE COVERAGE HONESTLY BEFORE YOU BUILD ON IT. A match's stream is per-point ONLY where a point-level feed covers it: `pbp_coverage: \"point\"` means a per-point stream has DELIVERED for this match — at least one played point past the `seq` 1 opener; `\"game\"` means no played point has arrived — only the snapshot score path covers it, or the stream holds only its opener so far (a listed match that has not started). An answer, not an error; it flips to `point` on the first played point. To admit a match as advancing, gate on `sequence > 1` (a seeded match is 1) together with `stale: false`. Per-point coverage is never promised slate-wide; ITF and qualifying coverage in particular is partial. `quality: \"revised\"` means the upstream feed rewrote an already-served prefix at least once during this match; served rows are never edited (append-only).\n\nEach row is the state AFTER a played point: `score`/`sets`/`games` (tiebreaks carry the running count in `score` with `games` frozen at the pre-breaker score), its position (`set`/`game`/`number`), `server` (of the next point), the derived `winner` (null when not attributable to a single point — never guessed), and `ts` — CAPTURE time, when our pipeline committed the state, because no feed asserts a per-point clock and we fabricate none.\n\nUp to 500 rows per page; `after_seq=last_seq` fetches the next page while `has_more` is true. 404 unknown match; 400 `points_disabled` while the surface is switched off server-side.\n\nCOMPLETED MATCHES: the stored live stream is served on a completed match too, whenever it is itself measured complete (the match-closing point included) or carries `serve`/`outcome` tags and is legal end to end (every transition one attributable point, judged in playing order). A projection never carries a clock or a tag, so a complete tagged stream is strictly more information than any reconstruction of the same match. Only when the stream falls short — no rows at all, incomplete and untagged, or a transition nobody can attribute — and a measured-complete recorded point sequence of the finished match exists does this endpoint serve THAT instead: the complete sequence projected into the same point-frame shape, love-love opener through the match-closing point, `seq` contiguous 1..N. The response field `basis` says which base served the page: `live` (the persisted live stream rows) or `reconstruction` (the projected complete sequence; `quality` is `clean`, every transition measured legal), and on `reconstruction` `basis_reason` says why the stream was not served: `stream_absent` (no stored stream rows), `stream_incomplete` (the stream is legal but does not measure complete — it joined mid-match or stopped short — and carries no tags) or `stream_illegal` (at least one transition is not attributable to one point: a gap or a torn row). When the reconstruction serves it serves wholesale — the two sequences are never interleaved (they share no key, so any merge would fabricate an order). On projected frames `ts` is null on every row: the recorded sequence carries no per-point clock and we fabricate none. `after_seq` pagination and `seq` dedup work identically on either basis, but the two bases are different sequences: if a completed match reads `reconstruction`, re-read from `after_seq=0` rather than resuming a live cursor into it. Precedence fixed 2026-09-21: until then a measured-complete recorded sequence displaced the stream unconditionally, so a completed match could lose its tags the moment a reconstruction landed.\n\nTHE MATCH-CLOSING POINT (added 2026-09-20). Every row is the state AFTER a point, so the point that wins a game is carried by the next game's `number: 0` opener — and the point that wins the match had no next row to be carried by: the live stream never held it, and a serve statistic built off the stream was missing every match's last point. On a COMPLETED match served on the `live` basis the page now closes with ONE terminal row: `seq` = last + 1, `number` 0, `sets`/`games` the final score, `score` `{\"p1\":\"0\",\"p2\":\"0\"}`, `tiebreak` false, `server` null (nobody serves next), `winner` the match winner, `ts` the instant the final score was observed. It is built at read time from the stream's last row and the observed final score, and only when the two are one point apart — the winner held game point and the final is the decided score; nothing is fabricated otherwise. `serve`, `outcome` and `tagged_at` on that row are null: no source's tag for a match's last point is stored yet. When the match ends in a tiebreak (added 2026-09-21) the stream's last row is the decisive tiebreak score itself (7-3, 8-6) and the closing row is the set roll-up after it: the next game number, `number` 0, `tiebreak` false, `sets` incremented for the tiebreak winner, the set banked 7-6 in `games`, `score` 0-0, `server` null, the same `winner` — the same row the stream stores after every other set-ending tiebreak. The response field `ends_at_final` says whether the sequence served ends on the match-closing point: `false` on a completed match whose stream stops short of it — a retirement or walkover (no closing point was played), a capture that stopped two or more points short, or a closer that cannot be stated as one point (from deuce, or from a 10-point match tiebreak). Always `false` on a live match. On the `reconstruction` basis it is judged from the projected sequence's last frame (a complete recorded sequence of a retired match ends at the retirement, so it reads `false` there). WebSocket and push frames are unchanged.\n\nREVISIONS: `changed_since` (added 2026-09-20). `after_seq` is a cursor by `seq`, so it can never return a row you already hold — and a `serve`/`outcome` tag that lands late lands on exactly such a row. Every row now carries `tagged_at`, the UTC instant its tags landed (null while none has). Pass `changed_since=` (e.g. `2026-09-20T00:35:18Z`; `Z` or an offset, a naive value is read as UTC, a date alone is refused) to get only the rows whose `ts` OR `tagged_at` is later than that instant, in `seq` order, paged like any other read and composable with `after_seq`. The post-match recipe: read the match, keep the instant, re-read with `changed_since=` and replace the rows you hold by `seq` — no socket, no full re-fetch. Anything that is not an ISO-8601 timestamp is a 400 `bad_changed_since`. On the `reconstruction` basis no row carries a clock or a tag, so a `changed_since` read of it is an empty page: that sequence is final at first read.", "operationId": "getMatchPoints", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "name": "after_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Return only points with `seq` greater than this — the resume cursor. Pass the `last_seq` of the previous page (or the last seq your WS stream delivered) to continue; 0 or absent reads from the start of the match. A non-integer or negative value is a 400 `bad_after_seq`." }, { "name": "changed_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Added 2026-09-20. Return only rows whose `ts` OR `tagged_at` is later than this instant — the revision filter for a reader without a socket, composable with `after_seq`. ISO-8601 with a `Z` or an offset (e.g. `2026-09-20T00:35:18Z`); a naive value is read as UTC; a date alone is not an instant and is refused. Anything that is not an ISO-8601 timestamp is a 400 `bad_changed_since`. An empty page on the `reconstruction` basis, whose rows carry neither a clock nor a tag." } ], "responses": { "200": { "description": "The point events page, seq order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchPoints" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/players": { "get": { "summary": "Search players by name (FREE)", "operationId": "searchPlayers", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Players (ranked first; no stats object on the list)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Player" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/players/{playerId}": { "get": { "summary": "One player's bio + ranking + cached stats (FREE)", "description": "`playerId` is a ROSTER id — the live player registry, the id space `/players`, `/matches` and `/rankings` all speak.\nIt is NOT the archive corpus person id. The results archive (1968–2022) keeps its own person registry, and archive match rows publish those ids as `winner.player_id` / `loser.player_id`. The two spaces are disjoint: no corpus id resolves here, and since 2026-09-20 a 404 for one says so and points at `/history/archive/players?id={playerId}`, which is where that id is read. A 404 with no `see` field is simply an id we do not hold.", "operationId": "getPlayer", "parameters": [ { "name": "playerId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Player with `stats` ({ratings, season})", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Player" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No roster player holds this id. When the id IS a corpus person id the body adds `detail` and `see` (the archive lookup); otherwise it is the plain `Error` body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerNotFound" } } } }, "410": { "$ref": "#/components/responses/PlayerGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tournaments": { "get": { "summary": "Tournament catalogue — the id space `Match.tournament_id` joins (FREE)", "description": "Stable tournament identity, one row per tournament × event type, stable across seasons. `city`/`country` come from a curated table and `category` only where our catalogues agree unambiguously on an exact-name join — each is null otherwise, never derived from the tournament name. Each row also carries the CURRENT season's `tier` / `tier_source` (added 2026-09-22) — the level in a closed vocabulary (`atp_500`, `challenger_125`, `wta_125`, `itf_w35` … | null); the tier is per season, so a match carries its own.", "operationId": "listTournaments", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match on the tournament name." }, { "$ref": "#/components/parameters/tour" }, { "$ref": "#/components/parameters/draw" }, { "name": "tier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tier filter (added 2026-09-24): comma-separated exact values from the same closed tier vocabulary as `Match.tier` (`?tier=atp_500`, `?tier=atp_500,challenger_100`). Selects tournaments whose own `tier` field carries one of the values, which on this resource is the **current season's** level, because a catalogue row has no season of its own. That is the one difference from `?tier=` on `/matches` and `/history/matches`, where the value is the level in each MATCH'S season (a tournament keeps one `tournament_id` while its level moves). Filter and field always read the same season on the same resource, so they cannot disagree. A tournament with no row for the current season matches no value: null means the level is unknown, not absent. Composes with `?tour=`, `?draw=` and `?search=`. Unknown value → 400 `bad_tier` with the offending values in `bad` and the full vocabulary in `allowed`." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Tournaments, name order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tournament" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tournaments/{tournamentId}": { "get": { "summary": "One tournament by its stable id (FREE)", "operationId": "getTournament", "parameters": [ { "name": "tournamentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The `tournament_id` carried on match objects." } ], "responses": { "200": { "description": "The tournament", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tournament" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/markets": { "get": { "summary": "The match's match-winner market (PRO)", "description": "The match-winner market mapped to this match — `data` holds at most one object, and `meta.count` is 0 when nothing is mapped.\n\nMATCH-WINNER ONLY. No handicaps or game spreads, no totals, no set-winner books, and no per-game or per-set derivative of any kind. A quote here is the probability that a player WINS THE MATCH. Venues do list tennis derivatives beside the match-winner book — game spreads such as \"A (-3.5) vs B (+3.5)\" among them — and this API deliberately publishes none of them: a derivative is refused at the mapping step so it can never be served as, or beside, a match-winner price (2026-09-22).", "operationId": "listMarkets", "parameters": [ { "name": "match_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Markets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } }, "meta": { "type": "object", "properties": { "match_id": { "type": "integer" }, "count": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/markets/{matchId}/prices": { "get": { "summary": "Market + recent price ticks per side, newest first (PRO)", "description": "The mapped match-winner market for one match, with its recent price ticks per side, newest first.\n\n404 with `error: no_market` (since 2026-09-02; `match_id` and `coverage: \"none\"` alongside) when no match-winner market is mapped to the match — a market is mapped only where one is published for that fixture, so a client walking every live match will meet this. A bare `not_found` means the match id itself does not exist. Every row of `GET /matches` carries `has_market`, so a slate can be filtered before any call here. `GET /matches/{matchId}` answers `200` for the same match with `market` and `market_price` set to `null` instead, and carries the live score in the same response, so a per-match poll built on the detail route never spends a call on a 404.\n\nTicks are kept for 30 days and then deleted: a market older than that answers with an empty `prices` array while staying mapped — retention, not a fault. For paging past 500 ticks use `/matches/{matchId}/prices` with its cursor.", "operationId": "getMarketPrices", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Market with `prices`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "description": "`error: not_found` — no such match id. `error: no_market` (with `match_id`, `coverage: \"none\"`, `detail`) — the match exists and no match-winner market is mapped to it; `has_market` on the match list says so without a probe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{matchId}/prices": { "get": { "summary": "Bare price ticks of the mapped match-winner market, newest first (PRO)", "description": "Recent ticks only (no market wrapper). `limit` caps at 500; `minutes` bounds the lookback window; `cursor` pages an older match. 404 `no_market` when the match exists but has no mapped market (404 `not_found` for an unknown id). Retention (since 2026-09-15): in-play ticks of a match with a mapped market — from live to completion, plus a five-minute pad — are kept at full resolution and not deleted; pre-match / idle ticks and unmapped markets keep the tiers (every tick for an hour, ~1/minute to 24h, ~1/5 minutes after, deleted after 30 days). Ticks stamped before 2026-09-15 were already thinned under those tiers.\n\nTicks are kept for 30 days and then deleted, so a match older than that answers an empty `data` while its market stays mapped — that is retention, not a fault. Past 500 ticks, page with the cursor: read a page, and while `meta.has_more` is true pass `meta.next_cursor` back as `?cursor=` for the next (older) page. Pages never overlap or skip a tick (added 2026-09-09).", "operationId": "listMatchPrices", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "minutes", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1440 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Keyset cursor for the next (older) page — the `meta.next_cursor` of the previous page (added 2026-09-09). Opaque; anything else is `400 bad_cursor`." } ], "responses": { "200": { "description": "Price ticks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "meta": { "type": "object", "properties": { "match_id": { "type": "integer" }, "count": { "type": "integer" }, "has_more": { "type": "boolean", "description": "The window was clipped at limit — older ticks exist. There is no offset here: pass `next_cursor` back as `?cursor=` for the next older page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Present (non-null) exactly when `has_more` is true — pass it back as `?cursor=` for the next older page (added 2026-09-09)." }, "limit": { "type": "integer" }, "minutes": { "type": [ "integer", "null" ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/matches/{matchId}/prices": { "get": { "summary": "Per-point price history — the match-winner quote in force at every played point (PRO)", "operationId": "listHistoryMatchPrices", "description": "One row per played point of a match with a mapped market, ascending by `seq` (added 2026-09-15). Each row carries the score state the BASIC tape publishes and, per neutral side (\"1\" = players.p1's outcome, \"2\" = p2's), the newest quote observed at or before the point's capture time — or, when none precedes it, the first quote after it within five minutes (negative lag). A side with no usable quote is null, never invented. `resolution` is an honest label of the join: tick (|lag| <= 15 s), minute (<= 90 s), coarse (older); matches played from 2026-09-15 align against the full-resolution in-play tape, earlier ones against the thinned tape and read minute/coarse. The ULTRA-only per-point fields (server, winner, serve, outcome) are not on this surface. Works on a live match too. 404 `no_market` when the match has no mapped market — enumerate with `GET /history/matches?has_market=true`.", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "name": "after_seq", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Resume cursor — return points with seq greater than this (meta.last_seq of the previous page). Anything but a non-negative integer is a 400 bad_after_seq." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Per-point price rows, ascending by seq", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PointPrice" } }, "meta": { "type": "object", "properties": { "match_id": { "type": "integer" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "last_seq": { "type": "integer", "description": "The resume cursor — pass back as ?after_seq= while has_more is true." }, "has_more": { "type": "boolean" }, "alignment": { "type": "string", "enum": [ "points", "none" ], "description": "points = the match has a per-point stream to align to; none = it has none (a reconstruction-only tape carries no point clock and no quote is fabricated — data is empty, not an error)." }, "resolution_counts": { "type": "object", "properties": { "tick": { "type": "integer" }, "minute": { "type": "integer" }, "coarse": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/matches": { "get": { "summary": "Completed matches, newest first, with derived winner and tape coverage (BASIC)", "description": "Requires BASIC on the live API, or any Historical Data API plan (Starter and up — see https://livetennisapi.com/historical-tennis-data-api). A FREE key may spend its 20 free history calls per calendar month here; past that the answer is `403 upgrade_required` carrying `free_history_taste: \"used\"`. All tours, January 2023 → now (deeper results live in the results archive, 1968–2022, at `/history/archive/matches`). Filter to a date range with `from`/`to`, and by `tour`, `draw` (singles/doubles), `player` (either participant) and `country` — same vocabulary as `/matches`. Each item carries a `tape` object saying what point-by-point data we hold for that match, so a whole page can be qualified in one call instead of one request per match. NOTE `?coverage=` is applied AFTER the page is cut, so a filtered page is routinely shorter than `limit` (and may be empty) while later pages still hold matching matches — a short filtered page is not an end-of-data signal; `?points_complete=` filters the same way. `?tier=` (added 2026-09-22) selects by the level the tournament was played at in the match's season, and `?restated_since=` (added 2026-09-22) keeps only the matches whose published result was corrected after an instant — the poll to run after each settlement pass.", "operationId": "listCompletedMatches", "parameters": [ { "$ref": "#/components/parameters/hasMarket" }, { "$ref": "#/components/parameters/isQualifying" }, { "$ref": "#/components/parameters/gender" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/playedFrom" }, { "$ref": "#/components/parameters/playedTo" }, { "$ref": "#/components/parameters/tour" }, { "$ref": "#/components/parameters/draw" }, { "$ref": "#/components/parameters/player" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/tournamentId" }, { "$ref": "#/components/parameters/tier" }, { "name": "coverage", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Coverage" }, "description": "Keep only matches whose tape has this coverage. An unknown value is a 400 `bad_coverage` listing the accepted values in `allowed`." }, { "name": "points_complete", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Keep only matches whose measured point-completeness ledger verdict is this value — best-basis (the served tape OR an on-disk reconstruction measured point-complete; fetch the latter with `?points=complete` on the per-match tape). The ledger is a per-match cache reconverged nightly. A match not yet measured matches NEITHER value; anything but true/false is a 400 `bad_points_complete`. Applied AFTER the page is cut, exactly like `?coverage=`." }, { "name": "restated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Keep only matches whose published result was CORRECTED after this instant (added 2026-09-22) — a `restatement` row on their status history later than it. The poll to run after recording results: anything it returns has a `result_restated_at` past your cursor and a `result_version` above the one you hold, and its status history says what changed. An ISO-8601 instant with a `Z` or an offset (a naive value is read as UTC); a bare date is a 400 `bad_restated_since` — a day is not an instant, exactly as for `changed_since`. Composes with every other filter here. A match whose correction was a reopen is `live` again and reappears here once re-completed, with a further `restatement` row. Rows with this basis exist from 2026-09-22; earlier corrections were not signalled and nothing is reconstructed for them." } ], "responses": { "200": { "description": "Completed matches (`winner` = 1|2|null, from final sets), each with its tape coverage", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryMatch" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/coverage": { "get": { "summary": "Measured completeness rollup per tour × draw bucket (BASIC)", "description": "Requires BASIC on the live API, or any Historical Data API plan (Starter and up — see https://livetennisapi.com/historical-tennis-data-api). A FREE key may spend its 20 free history calls per calendar month here; past that the answer is `403 upgrade_required` carrying `free_history_taste: \"used\"`. The numbers to read BEFORE choosing what to backtest, in one call instead of paging the archive. A PREBUILT snapshot rebuilt nightly right after the completeness ledger reconverges — never computed at read time — so `as_of` (= `built_at`) dates every number, and `ledger_max_computed_at` is the newest underlying per-match measurement. Buckets are atp/wta/challenger/itf/juniors × singles/doubles plus `other` (team ties, mixed, exhibitions, and matches with no stated event type — counted, never dropped, so the totals cannot lie), derived from the same registries as the `tour` and `draw` fields. `method` states the full measurement rule in one paragraph, so every number carries its own definition. As of 2026-08-18 the headline spread it exposes: 51.1% of ITF singles matches are point-complete on the best basis against 3.5% of ITF doubles — do not extrapolate a completeness rate across a tour group.", "operationId": "getHistoryCoverage", "responses": { "200": { "description": "The rollup artifact, dated by its own as_of", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageRollup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "coverage_unavailable — the artifact has not been built yet (or is unreadable). Honest and temporary; retry after the nightly build. The rollup is never computed inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/history/matches/{matchId}": { "get": { "summary": "Per-match tape — point-by-point score + per-point model probabilities (BASIC)", "description": "The tape is the point-by-point score sequence we hold for this match — every recorded score row including the model fields `win_probability_p1` and `danger` at that point — plus match metadata and the model profiles produced during the match. The model fields here are part of the paid History product by design, distinct from the ULTRA-gated LIVE model fields. One match per request. Requires BASIC on the live API, or the Historical Data API Starter plan and up.\n\nThe tape is NOT guaranteed to cover the whole match — check `meta.coverage` and `meta.point_source` before backtesting. Rows expanded after the fact from a finished-match point-by-point record carry a null `timestamp` and null model fields; nothing is ever synthesised.\n\nWORKS ON A LIVE MATCH, not only a completed one. The tape is assembled from whatever has been committed so far, so it is how you read the point-by-point history of a match in progress — including games played before you started watching, where we were already watching them. The LIST endpoint is completed-only; get live ids from `/matches?status=live`. `/matches/{matchId}/score` is one state; this is the sequence of states.", "operationId": "getMatchTape", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "name": "sequence", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "raw", "clean" ], "default": "raw" }, "description": "`raw` (default) is every row we committed, in commit order — deliberately non-monotonic, since independent sources race and a higher-trust one may correct a lower-trust one backwards. `clean` returns one row per distinct score state, keeping the last assertion of each, ordered by MATCH PROGRESS (the same ranking our arbiter uses), not by wall clock — so array order is the authoritative point order, and `timestamp` values may locally disagree with it by a few seconds where a stale re-assertion carried a later clock. Within a game, deuce states legitimately cycle (40-40 ↔ AD) and rank equally, so consecutive clean rows are not guaranteed point-monotonic there; `point_winner` is only set where the transition is a single attributable point. `winner` (since 2026-09-22) rides every row of EITHER sequence with the same verdict: on the raw sequence it is judged against the previous raw row, so a re-send reads null there and collapses away here. An unknown value is a 400 `bad_sequence`." }, { "name": "points", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "complete" ], "default": "default" }, "description": "`default` serves observed rows first — what our own pipeline committed, a SAMPLED record of the match. `complete` is the explicit opt-out of that precedence for consumers who want every point: where a whole-match reconstruction exists it is served WHOLE, in its own point order, with `point_winner` (and `winner`, the same verdict) on every row and null timestamps/model fields per the reconstruction contract. Where none exists, the response is exactly the default read plus `meta.points` (whose `available_complete` tells the cases apart) — no error. Cannot combine with `sequence=clean` (400 `bad_combination` — the state-key collapse would delete the repeated deuce states a complete point sequence contains). An unknown value is a 400 `bad_points`; where not yet enabled, `complete` answers 400 `points_read_disabled` rather than silently serving the default. `coverage` and `meta.points` are orthogonal axes: coverage says how the rows were OBTAINED, points says how COMPLETE the sequence is — completeness is only ever claimed per match, as measured." } ], "responses": { "200": { "description": "The full tape (`match` + `tape` + `profiles` + coverage `meta`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryTape" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/incidents": { "get": { "summary": "Published data-quality incidents (BASIC)", "description": "Every data-quality incident we have published, oldest window first. This is the register to reconcile against when a published value changed after you read it: each record states the window it applies to, the rule before and after, what the defect was, which surfaces it touched, how to tell an affected row from a clean one, and whether corrections and a per-match list are available. Nothing here is inferred at read time. The register is part of a release, so a record appears only when we have decided what it says, and it does not change between releases.", "operationId": "listHistoryIncidents", "responses": { "200": { "description": "The incident register.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "kinds": { "type": "array", "items": { "type": "string" } }, "generated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/incidents/{incidentId}/matches": { "get": { "summary": "The matches one incident affected, as JSONL or CSV (BASIC)", "description": "One row per affected match, streamed as JSONL by default or CSV with `?format=csv`. Columns are `incident_id`, `match_id`, `tournament`, `tour`, `round`, `draw_stage`, `scheduled_time`, `affected_field`, `served` and `expected`. `served` and `expected` carry that incident's own vocabulary: for the deciding-set rule `match_tiebreak` against `full_set`, for the price side `side_reversed` against `side_players`, and for a field repair the before and after values. Rows are derived from stored data by the same code every consumer of that field uses. A match whose derivation would be a guess is left out, and the incident's `matches.note` says which those are, so this export is exact rather than complete.", "operationId": "listIncidentMatches", "parameters": [ { "name": "incidentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "jsonl", "csv" ], "default": "jsonl" } } ], "responses": { "200": { "description": "One row per affected match, as a file attachment.", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "`bad_format` — `format` was neither `jsonl` nor `csv`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "description": "`not_found` for an unknown incident id. `not_derivable` for an incident with no exact per-match derivation, carrying that incident's `window_utc`, `affected_surfaces` and the note saying why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/archive/matches": { "get": { "summary": "Results archive (1968–2022) — deep historical results (BASIC)", "description": "Completed-match RESULTS from a licensed historical corpus — ATP and WTA main draws, qualifying/challengers and futures tiers, 1968 through 2022. Winner/loser-shaped records with final score, round, seeds, the players' ranks AT THE TIME, and per-match serve statistics where the era recorded them. Requires BASIC on the live API, or any Historical Data API plan (Starter and up).\n\nA SEPARATE id space from `/matches` — archive people are identified by the corpus person id and by name, never by roster player ids — and the archive ends where our own point-by-point coverage begins (2023-01), so no match is ever served from two datasets. `event_date` is the TOURNAMENT START date, the only date records of this era carry.", "operationId": "listArchiveMatches", "parameters": [ { "name": "tour", "in": "query", "schema": { "type": "string", "enum": [ "atp", "wta" ] }, "description": "The archive covers the ATP and WTA corpora only." }, { "name": "name", "in": "query", "schema": { "type": "string", "minLength": 3 }, "description": "Case-insensitive substring match on EITHER player's name (min 3 chars)." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Earliest tournament start date (`YYYY-MM-DD`)." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Latest tournament start date (`YYYY-MM-DD`)." }, { "name": "round", "in": "query", "schema": { "type": "string", "enum": [ "F", "SF", "QF", "R16", "R32", "R64", "R128", "RR", "BR", "Q1", "Q2", "Q3", "Q4", "ER" ] }, "description": "The archive's controlled round vocabulary." }, { "name": "level", "in": "query", "schema": { "type": "string" }, "description": "Source tier code: G=grand slam, M=masters, A=tour, F=finals, D=davis cup, C=challenger, O=olympics; the futures tiers carry their category codes (e.g. 15, 25) as published." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Archive results, newest tournament first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ArchiveMatch" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/archive/matches/{archiveId}": { "get": { "summary": "One archive result, with serve statistics where recorded (BASIC)", "description": "Same entitlement as the archive listing. `stats` is null for the (mostly pre-1991) rows the source never recorded statistics for — never synthesised. A result played 2013–2022 may also have a reconstructed point-by-point tape at `/history/archive/matches/{archiveId}/tape`; the RESULT stays on BASIC either way.", "operationId": "getArchiveMatch", "parameters": [ { "name": "archiveId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The archive record, `stats` included where the era recorded them", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveMatch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/archive/matches/{archiveId}/tape": { "get": { "summary": "Reconstructed 2013–2022 point-by-point tape for one archive result (ULTRA, or any History plan)", "description": "The score sequence behind a 2013–2022 archive result, REBUILT FROM THE PUBLIC RECORD. The result tells you what happened; this tells you how.\n\nNOBODY WATCHED THESE MATCHES, and every field that would imply otherwise is null. `timestamp` is null on every row — not by convention, but because the production table has no timestamp column at all, so no repair, backfill or re-archive can put a wall clock on a 2016 row, and the promotion script refuses to run if such a column ever appears. `win_probability_p1` and `danger` are null on every row: the model was not running in 2016 and nothing has been back-computed and served as if it had been (`meta.model_rows` and `meta.observed_rows` are both 0, always). `profiles` is always `[]`. The rule we publish for the 2023+ tape — a non-null `timestamp` means we watched that point live — holds across both halves of the product.\n\nYEARS: 2013–2022 ONLY. 97,901 matches and 14,340,663 rows. The results archive holds a further 977,903 matches from 1968–2012 and NONE of them has a tape — there is no public point-by-point record of those years to rebuild and we do not manufacture one. A match with no tape answers 404, which is also the answer when a tape exists and failed the proof below; the two are deliberately not distinguished.\n\nCOVERAGE OF THE ERA, thin spots beside the strong ones: 19.3% of archive matches played 2013–2022 overall, 44.9% of tour-level play. Main-draw tour buckets run 91.6–98.7% (ATP Masters 98.7%, ATP slam 98.0%, WTA Premier Mandatory 97.9%, WTA slam 97.4%, ATP 250–500 95.4%, WTA Premier 94.1%, WTA International 91.6%); ATP Challenger main draws 55.3% and Challenger qualifying 33.6%; slam QUALIFYING is thin at 16.0% (ATP) and 18.1% (WTA); ITF and futures are effectively absent — 25 of 116,575 ATP futures matches, 68 of 19,162 ITF M15, 48 of 9,380 ITF M25 — and this product does not cover them. If your work is ITF, this is the wrong dataset and we would rather you knew now. 31.0% of the corpus is qualifying-draw play, which is unusual at this scale and is the part you are least likely to hold already.\n\nHOW A TAPE IS BOUND TO ITS MATCH. A tape attached to the wrong match is silent, permanent and poisons anything trained on it, so each one proves five things before publication: the EDITION binds by majority vote onto one archive tournament; the NAMES resolve to exactly one archive row with an unambiguous orientation; the ROUND agrees through an explicit map (this is what separates the qualifying and main-draw meetings of the same pair inside one edition); the SET SPINE derived from the rows equals the published final score exactly (a retirement matches on a one-directional prefix rule — a tape may stop short, never run past the printed score); and the vendor DATE lies inside the tournament's window. The tape is then walked step by step against 23 interior invariants — games and sets never regress or jump, a closed set holds a score a set can actually finish on, a tiebreak is flagged only where one can be played, points never run backwards inside a game, `seq` is contiguous. A tape that fails any clause or any invariant is REFUSED WHOLESALE rather than published against a guess, which is why this endpoint answers 404 instead of serving a probable match.\n\n`archiveId` is an `archive_matches.id` (the `id` on a `/history/archive/matches` row), NOT a match id — the two are separate, overlapping integer spaces, so passing one to the other's routes resolves a different, real record without erroring. The response names it `meta.archive_match_id` for exactly that reason. Rows are WINNER-FIRST (`sets[0]` / `games[0]` / `points[0]` are the winner's, `server: 1` means the winner was serving), unlike the p1/p2-shaped 2023+ tape — a live match has no winner while it is being played.\n\nThis operation takes NO query parameters: `sequence` and `points` are ignored rather than refused. `meta.sequence` is always `raw` — a reconstructed tape has one source and no corrections, so there is nothing for a clean collapse to remove.\n\nTier: core ULTRA, or any active History plan (Starter included, which opens it on a FREE core key). The archive RESULT itself (`GET /history/archive/matches/{archiveId}`) stays on BASIC — core BASIC and core PRO read the result and are refused the tape, and the refusal is `403 upgrade_required` carrying `capability: archive_tape`. The per-year BULK files (`?kind=archive_tape`) are a separate gate: core ULTRA, or a History Pro/Business subscription, or an active one-off package window.", "operationId": "getArchiveTape", "parameters": [ { "name": "archiveId", "in": "path", "required": true, "description": "An `archive_matches.id` — the `id` on a `/history/archive/matches` row, never a match id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The reconstructed tape (`match` + `tape` + `tiebreaks` + an always-empty `profiles` + provenance `meta`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveTape" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "description": "No tape for this archive result — it is 1968–2012, it is 2013–2022 and was never reconstructed, or a reconstruction exists and did not prove its binding. The three are deliberately not distinguished: \"we hold something we will not stand behind\" is not a state this product reports.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/archive/players": { "get": { "summary": "Archive player bios — hand, DOB, country, height, career-high (BASIC)", "description": "People of the results archive (1968–2022), in their own id space — `id` is the corpus person id that archive match rows carry as `winner.player_id` / `loser.player_id`, scoped per tour; never a roster id. Career-high rank and the earliest week it was reached are computed offline from the corpus's own weekly ranking tables. Null fields are the era's silence, never guessed. Requires BASIC, or any Historical Data API plan.", "operationId": "listArchivePlayers", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Look a person up BY the corpus person id — the value archive match rows publish as `winner.player_id` / `loser.player_id`. This is the only place that reads the PERSON by that id; the one other surface taking it, `/rankings?archive_player=`, is ULTRA, requires `system=elo`, and answers with ratings rather than a bio. Corpus ids and roster ids are disjoint id spaces, so the same value on `/players/{playerId}` returns 404 (that 404 now points here). Returns every person wearing the id — the tours number independently and some ids are live in both — so add `tour` to narrow it to exactly one, the same rule `archive_player=` applies." }, { "name": "player_id", "in": "query", "schema": { "type": "integer" }, "description": "Alias of `id`, under the name the same value carries on an archive match row. Sending both with different values is a 400." }, { "name": "name", "in": "query", "schema": { "type": "string", "minLength": 3 }, "description": "Case-insensitive substring filter (min 3 chars)." }, { "name": "tour", "in": "query", "schema": { "type": "string", "enum": [ "atp", "wta" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Archive people, ordered by name", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ArchivePlayerBio" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/archive/career": { "get": { "summary": "Career aggregates over the results archive, 1968–2022 (BASIC)", "description": "One player's whole archive career in one response: W-L record (overall, by surface, by level, by year), titles, and the summed serve-stat block with derived ratios. Everything is a sum or a ratio of sums over rows you can fetch individually from `/history/archive/matches` — nothing is modelled. `serve.matches_with_stats` states the coverage honestly: the corpus records per-match serve statistics from 1991 only, so a 1970s career has a full W-L record and an empty serve block. Ambiguous name fragments are refused with candidates, and an exact name selects its person even where a longer name contains it (same rule as `/h2h`); an unknown name is a 404. Requires BASIC, or any Historical Data API plan.", "operationId": "getArchiveCareer", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3 }, "description": "Player name (fragment, min 3 chars — must resolve to one person)." } ], "responses": { "200": { "description": "The career aggregate body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveCareer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/h2h": { "get": { "summary": "Head-to-head across the results archive (1968–2022) and our own completed matches (2023→now) (BASIC)", "description": "The record between two players, assembled from BOTH halves of the product: the results archive, where the winner is a stored column, and our own completed matches, where the winner is derived from the final recorded state. Names are the keys — archive people have no roster ids. A fragment matching more than one player is refused with the candidate list (`400 ambiguous_name`), because two people summed into one record is a wrong answer, not a convenience. Passing a name EXACTLY selects that person, even where a longer name contains it, so `Carlos Alcaraz` resolves although `Carlos Alcaraz Gonzalez` also exists. A name you did not type in full stays a fragment: `Sinner` still refuses, and lists Jannik and Martin. Totals count meetings with a KNOWN winner; `undecided` counts the rest. Walkovers and retirements are part of the record, and each meeting carries `outcome` so you can exclude them. Requires BASIC, or any Historical Data API plan. On ULTRA, a per-player `stats` block adds serve/return/break-point aggregates over the pairing: `archive_serve` (serve-side, from 1991) and `current` (2023+, adding return and break-point conversion, aces and winners), each with `meetings_with_stats`.", "operationId": "getHeadToHead", "parameters": [ { "name": "p1", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3 }, "description": "First player name (fragment, min 3 chars)." }, { "name": "p2", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3 }, "description": "Second player name (fragment, min 3 chars)." } ], "responses": { "200": { "description": "The head-to-head record; empty totals when no player matches the names", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadToHead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/packages": { "get": { "summary": "List the pre-built monthly bulk history packages (PRO)", "description": "Bulk downloads are a heavier product than single-match tape reads. Requires PRO on the live API, or the Historical Data API Pro plan and up, or a one-off package access pass. A key that can read the tape but is not package-entitled receives `403 upgrade_required`.", "operationId": "listHistoryPackages", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tape", "rankings", "rally", "archive", "elo", "archive_tape" ], "default": "tape" }, "description": "Package family. `tape` (default) = monthly point-by-point match tapes; `rankings` = as-of ranking records (ULTRA); `rally` = the charted rally corpus (shot-by-shot) as YEARLY exports (ULTRA); `archive` = the results archive (1968–2022) as YEARLY exports, same entitlement as the tape packages; `elo` = the as-of Elo tape as YEARLY exports (ULTRA); `archive_tape` = the RECONSTRUCTED 2013–2022 point-by-point tape as YEARLY exports — ten periods, 2013 through 2022, each with a JSONL and a CSV file, all `ready`, needing ULTRA or a History Pro/Business subscription or an active one-off package window (a History Starter grant reads a tape per call and does not download years of them). The yearly kinds' `period` is `YYYY`, one file per year, because a fixed historical corpus is not an accruing monthly stream. The default means a tape-only client never sees a new kind of row appear." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}$" }, "description": "Year archive listing — every published month of the year (History Business, a 1-year package, or ULTRA)." } ], "responses": { "200": { "description": "Ready packages, newest period first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryPackage" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "year": { "type": "string", "description": "Echoed only when `?year=` was supplied." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/packages/{period}": { "get": { "summary": "One monthly package — manifest, or the bulk file itself (PRO)", "description": "Without `format` returns the package manifest (file set, counts, sha256). With `format=jsonl` or `format=csv` streams that file as an attachment. Same entitlement as `/history/packages`. 404 when the month has not been built yet — list available months first.", "operationId": "getHistoryPackage", "parameters": [ { "name": "period", "in": "path", "required": true, "description": "Calendar month, `YYYY-MM` — except for the yearly kinds (`rally`, `archive`, `elo`, `archive_tape`), where it is the bare year `YYYY` (`400 bad_period` otherwise).", "schema": { "type": "string", "pattern": "^\\d{4}(-\\d{2})?$" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tape", "rankings", "rally", "archive", "elo", "archive_tape" ], "default": "tape" }, "description": "Package family; `rankings`, `rally`, `elo` and `archive_tape` require ULTRA, a History Pro/Business subscription, or an active one-off package window (changed 2026-08-19). `rally` = the yearly charted rally corpus exports; `archive` = the yearly results archive (1968–2022) exports, same entitlement as the tape packages; `elo` = the yearly as-of Elo tape exports; `archive_tape` = the yearly reconstructed 2013–2022 point-by-point tape exports (`period` 2013 through 2022 — no other year exists)." }, { "name": "format", "in": "query", "required": false, "description": "Omit for the JSON manifest; set to download the file. `corrections` (added 2026-09-10) streams the package's correction CSV — `match_id, field, before, after, tournament_key, source, corrected_at` — when stored data was repaired after the package was published; the manifest's `files` lists it with `format: corrections`, and a package without one answers 404 `no corrections file for that package`. First use: the 2023-02 → 2024-12 tape packages carry `surface` corrections for 19,439 Challenger matches (repaired 2026-09-10; the packages themselves were rebuilt the same day).", "schema": { "type": "string", "enum": [ "jsonl", "csv", "corrections" ] } } ], "responses": { "200": { "description": "The manifest (no `format`), or the bulk file as an attachment (`format=jsonl` streams NDJSON, `format=csv` streams CSV, `format=corrections` streams the correction CSV). A gzipped file (see the manifest's `compression`) is served as `application/gzip`, never with `Content-Encoding: gzip` — the manifest's `sha256` covers the exact bytes you receive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPackage" } }, "application/x-ndjson": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/fixtures": { "get": { "summary": "Upcoming scheduled fixtures, earliest first (FREE)", "operationId": "listFixtures", "parameters": [ { "$ref": "#/components/parameters/tour" }, { "$ref": "#/components/parameters/draw" }, { "$ref": "#/components/parameters/isQualifying" }, { "$ref": "#/components/parameters/gender" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Fixtures with start time and player ids where resolved — the nulls are real states, not gaps (names are always present)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fixture" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage": { "get": { "summary": "Your own usage vs quota (FREE — any tier)", "description": "Durable daily usage for the calling key: tier, limits, today's calls (current to the second) and a 30-day history. The per-minute window is on the X-RateLimit-* headers of every response, not here. Calls to this endpoint are quota-exempt — checking your usage never consumes it.", "operationId": "getUsage", "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rankings": { "get": { "summary": "Rankings and Elo — rank-ordered listing (PRO) or per-player as-of records (ULTRA); the as-of Elo tape is ULTRA in both modes", "description": "Returns, per ranking system, the newest record effective ON OR BEFORE `as_of` — never one dated after it. Every other ranking field in this API is the player's CURRENT value joined at read time, so replaying an old match elsewhere shows today's ranks; this endpoint is the point-in-time answer. Systems are never collapsed into a single \"rank\": ATP/WTA and the ITF circuits carry rank+points, UTR carries a rating with null rank and points because it has neither. `meta.coverage.oldest_available` gives the earliest date each system can answer for — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29) and nothing earlier can be reconstructed.\n\nTWO MODES — with `player` ids (ULTRA) — the per-player point-in-time records described above. WITHOUT `player` (PRO) — the FULL published table in rank order for exactly one `system`, the newest week at or before `as_of`; rows carry `player_name` as published and a null `player_id` for players outside our roster, so the table has no silent holes. `utr` has no listing (a rating, not a ranking).\n\nSYSTEM=UTR — observed ratings, honestly bounded. UTR records are observed from UTR's public search: a rating UTR withholds appears as ABSENT, never as 0, and `rating` is the only populated value — `rank` and `points` are always null. Per-player as-of ONLY — there is deliberately no UTR listing, because a table of only the players we happen to track would be a fake leaderboard. Per-player history accumulates from 2026-07-29; scattered earlier single-snapshot observations reach back to 2026-06-01. Coverage is a deliberate bias, not a roster mirror: the 24-hour sweep targets players with no official rank and no Elo rating (so it skews ITF), and among players active in the last 60 days it holds 931 of 5,606 ITF players (16.6%), 197 of 1,903 Challenger (10.4%), 43 of 573 WTA (7.5%) and 15 of 525 ATP (2.9%) — measured 2026-08-17.\n\nSYSTEM=ELO — THE AS-OF ELO TAPE (ULTRA in BOTH modes). Our own computed Elo for 65,622 players on four independent ladders (overall, hard, clay, grass), back to 1877 (ATP) and 1968 (WTA), covering the main tours plus challengers plus the futures tier. It answers what a player was rated BEFORE a given match, which is the only shape a backtest can consume. It is a HISTORICAL TAPE rather than a live leaderboard — the corpus behind it is fixed and no longer receives new results, so `meta.coverage.newest_available` states the tape's head date on every response (2026-06-15 at publication), and you should read it before treating the table as current. A week's results become effective 14 days after that week begins — strictly after the longest event in tennis — so the failure direction is staleness, never look-ahead. `rating` is the Elo. `rank` is LISTING MODE ONLY and is null in per-player mode, because an Elo has no global rank at a past instant until you say which field and which activity window you mean. `points` is always null. `matches` is the count on THAT ladder, published so that a rating still near its 1500 cold start is visible rather than inferred. A ladder a player has never played is omitted, never substituted. Ratings are on our own scale, are not comparable with Elo published elsewhere, and do not decay — a surface played only a few weeks a year (grass in particular) moves slowly, so a rising player can sit below an established one for several seasons while beating them. A CURRENT per-player Elo remains free on `GET /players/{id}`; this is the point-in-time series, the leaderboard and the bulk export. That free rating is sourced differently and sits on a DIFFERENT scale — the two differ by roughly 150 Elo of per-player standard deviation — so never present a rating from one scale against a rating from the other. The Elo listing REQUIRES `tour` — the ATP and WTA walks are disjoint, so a combined leaderboard would not be comparable — and takes exactly one `surface` (default `overall`). `elo` is never implicit — omitting `system` returns the official systems only.", "operationId": "listRankings", "parameters": [ { "name": "player", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "maxItems": 50 }, "explode": true, "description": "Player id — repeatable, max 50 (ULTRA per-player mode). OMIT it for the rank-ordered listing mode (PRO), which then requires exactly one `system`." }, { "name": "archive_player", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "maxItems": 50 }, "explode": true, "description": "Historical-corpus person id — repeatable, max 50, `system=elo` only, and REQUIRES `tour` because that id is only unique within one tour. It is the same id `GET /history/archive/players` returns as its `id`. Use it to reach the ~62,000 rated people who have no row in our player roster; `player` reaches the rest." }, { "name": "tour", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "atp", "wta" ] }, "description": "REQUIRED for an `elo` listing and for `archive_player`. The ATP and WTA Elo walks are disjoint universes whose players never meet, so a combined leaderboard would not be comparable. On an OFFICIAL system it is accepted when it agrees with that system's own tour (`system=atp&tour=atp`) and REFUSED with 400 when it contradicts it. CORRECTION 2026-09-20: until that date `system=atp&tour=wta` returned 200 and the ATP table — the parameter was accepted and ignored. If you sent a contradicting pair, the rows you received were the table named by `system`." }, { "name": "surface", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "overall", "hard", "clay", "grass" ] } }, "explode": true, "description": "`system=elo` only. Listing mode takes exactly one (default `overall`); per-player mode is repeatable and defaults to all four ladders. A ladder the player has never played is omitted, never substituted. REFUSED with 400 when no requested system is `elo` — there is no clay ATP ranking, so the filter cannot be made to act. CORRECTION 2026-09-20: until that date `system=atp&surface=clay` returned 200 and the OVERALL ATP table. A mixed `system=atp&system=elo&surface=clay` still passes, because an elo system is present." }, { "name": "min_matches", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 20 }, "description": "`system=elo` listing only. Minimum matches on that ladder. Every ladder starts at 1500, so without a floor the top of the table is players who won a handful of matches from the starting rating. Echoed back in `meta.coverage.qualified`. REFUSED with 400 when no requested system is `elo` (2026-09-20); it was previously accepted and ignored." }, { "name": "activity_weeks", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 104, "default": 52 }, "description": "`system=elo` listing only. The ladder must have moved within this many weeks of `as_of`. Elo does not decay, so without an activity window every leaderboard is topped permanently by players who have stopped playing. Echoed back in `meta.coverage.qualified`. REFUSED with 400 when no requested system is `elo` (2026-09-20); it was previously accepted and ignored." }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD. Omit for the latest known record." }, { "name": "system", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "atp", "wta", "itf_jt", "itf_mt", "itf_wt", "utr", "elo", "atp_doubles", "wta_doubles" ] } }, "explode": true, "description": "Restrict to one or more systems. Omit for all of the official systems — `elo`, `atp_doubles` and `wta_doubles` are NEVER included implicitly and must be named (a doubles tie prints as repeated ranks, as the publisher prints it), so an existing request's response is unchanged. Naming a system your plan does not cover refuses the whole call with 403 rather than silently returning the part you are entitled to." }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Ranking records in force at `as_of`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingRecord" } }, "meta": { "$ref": "#/components/schemas/RankingListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rally/matches": { "get": { "summary": "Charted matches with shot-by-shot data (ULTRA)", "description": "Charted matches, newest first. RALLY CONSTRUCTION IS THE LAYER BELOW THE TAPE: the tape says what the score became after each point, this says how the point was played.\n\nIt has its OWN id space. The charted corpus and our own match table are different populations — the corpus reaches back decades and concentrates on the biggest events, while our matches begin when our own collection did. Keying this on our match ids would hide most of it. Ask this endpoint for the authoritative coverage list rather than assuming a match is charted: charting is human work, so coverage is deep, not universal.", "operationId": "listRallyMatches", "parameters": [ { "name": "player", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Substring match on either player name." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`YYYY-MM-DD`." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`YYYY-MM-DD`." }, { "name": "surface", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "M", "W" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Charted matches, with per-match parse-quality counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RallyMatch" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rally/matches/{rallyMatchId}": { "get": { "summary": "Rally construction for one charted match (ULTRA)", "description": "One charted match with its points, in play order. Paged with `limit`/`offset`; `meta.total` is the match's full point count.", "operationId": "getRallyMatch", "parameters": [ { "name": "rallyMatchId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "The charted match with its `rally` points", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RallyMatch" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ListMeta" }, "rally": { "type": "array", "items": { "$ref": "#/components/schemas/RallyPoint" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/history/matches/{matchId}/rally": { "get": { "summary": "Rally construction by OUR match id (ULTRA)", "description": "Rally construction addressed by OUR match id, resolved through the optional link. Answers `404 {\"error\":\"not_charted\"}` when we hold the match but nobody charted it — deliberately distinct from \"no such match\", because most of our matches are not charted and a consumer walking the archive must tell them apart.", "operationId": "getMatchRally", "parameters": [ { "$ref": "#/components/parameters/matchId" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "The charted match with its `rally` points", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RallyMatch" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ListMeta" }, "rally": { "type": "array", "items": { "$ref": "#/components/schemas/RallyPoint" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/MatchGone" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/charting/players": { "get": { "summary": "Career shot-level charting aggregate for one player (ULTRA)", "description": "The deepest serve/return profile we hold, from the Match Charting Project: serve placement (deuce/ad × wide/body/T), return depth and outcomes, net and serve-and-volley conversion, clutch break/game/set-point serving and returning, winners and unforced errors by wing, and rally-length and shot-direction tendencies — summed over the player's charted matches. `name` (min 3 chars) is the key; a fragment matching more than one charted person is refused with the candidate list, and `gender=men|women` disambiguates. An exact name selects its person even where a longer name contains it (same rule as `/h2h`), while one name charted under both genders still refuses, which is what `gender` is for. Every field is a raw SUM over the player's Total rows and `matches_charted` states the sample. COVERAGE IS CURATED — 11,803 charted matches across both tours back to the 1960s, concentrated on the majors, NOT full-slate coverage.", "operationId": "getChartingPlayer", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3 }, "description": "Player name (fragment, min 3 chars)." }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "men", "women" ] }, "description": "Disambiguates a fragment that matches one charted person per tour side." } ], "responses": { "200": { "description": "The player's summed charting families with the sample size", "content": { "application/json": { "schema": { "type": "object", "properties": { "player": { "type": "object" }, "matches_charted": { "type": "integer" }, "coverage": { "type": "string" }, "families": { "type": "object", "description": "Per-family summed numeric columns." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/charting/matches/{chartingMatchId}": { "get": { "summary": "One charted match, every stat family for both players (ULTRA)", "description": "Every Match Charting Project stat family for one charted match, both players, with the per-set split (row/set 1, 2, Total) exactly as charted. `chartingMatchId` is this product's own id space (1960–2026, mostly matches with no counterpart in the live table).", "operationId": "getChartingMatch", "parameters": [ { "name": "chartingMatchId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The charted match's stat families, both players, per set", "content": { "application/json": { "schema": { "type": "object", "properties": { "charting_match_id": { "type": "integer" }, "mcp_id": { "type": "string" }, "gender": { "type": "string" }, "players": { "type": "object" }, "families": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks": { "post": { "summary": "Register an outbound webhook (ULTRA, direct keys only)", "description": "We POST the same frames the WebSocket sends to your HTTPS endpoint on every live score commit. Up to 3 webhooks per key (`409 webhook_limit` past that). The response is the ONLY time the signing secret is shown — store it.\n\nEach delivery carries `X-LTAPI-Signature` (`sha256=` — HMAC-SHA256 of the RAW request body with your webhook secret; verify with a constant-time compare), `X-LTAPI-Timestamp` (Unix seconds at send time — reject stale replays at your edge) and `X-LTAPI-Event` (the frame type: `score`, `break_point`, `break_point_result` or `point`).\n\nDelivery is best-effort, at-most-once, no replay: one attempt per frame with a ~3s timeout and redirects disabled. Every `score` frame is the complete current score, so a missed delivery self-corrects on the next commit. A `point` frame is an EVENT, not a state — a missed one does NOT self-correct; recover it with `GET /matches/{matchId}/points?after_seq=` and dedup by `seq`. After 25 consecutive failures the webhook is disabled automatically (`enabled:false`, `last_error` set — visible in `GET /webhooks`); delete and re-register to resume.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "HTTPS only, publicly routable" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "score", "break_point", "point", "status", "stoppages" ] }, "default": [ "score" ], "description": "`score` = every accepted live-score commit; `break_point` = the derived `break_point` / `break_point_result` frames; `point` = one POST per live point (the `PointFrame` shape), where that surface is enabled and the match has `pbp_coverage: \"point\"`." } } } } } }, "responses": { "201": { "description": "Created — includes `secret` (shown exactly once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "409": { "description": "Webhook limit reached (3 per key) — delete an existing webhook first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "summary": "List your webhooks (ULTRA, direct keys only; never includes the secret)", "operationId": "listWebhooks", "responses": { "200": { "description": "Your webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{webhookId}": { "delete": { "summary": "Remove one of your webhooks (ULTRA, direct keys only)", "operationId": "deleteWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/broadcast/match/{matchId}": { "get": { "summary": "One flat object for on-air graphics (ULTRA)", "description": "Added 2026-09-24, from a broadcaster's request. ONE flat JSON object for one match, built so a graphics template can bind each field to a fixed path.\n\nThree properties make it different from `GET /matches/{matchId}`, and each exists because a graphics pipeline breaks without it. The object is FLAT — no nested score object, no arrays of arrays. Every key is PRESENT on every read: a value we do not hold is `null`, never missing, because a missing key breaks a template binding. And the score is already in DISPLAY form — `p1_points` reads `\"40\"` or `\"AD\"`, `set_line` is one string such as `\"5-7 2-0\"`, and each set has its own column — so nothing has to be formatted downstream.\n\nIt is a PROJECTION of what the public API already publishes: the match object, its embedded score and the model probability, plus the break-, set- and match-point flags derived by the same classifiers the scoring pipeline uses. Nothing here is a new fact and nothing is guessed.\n\nBUILT FOR 1 Hz. Every response carries a strong `ETag` and `Cache-Control: no-cache, max-age=1`; send `If-None-Match` and an unchanged state costs a 304 with no body. ULTRA's burst window is 600 requests a minute, so ten single-match pollers at 1 Hz fit on one key. Detect a new state on `sequence`, not on `served_at`, which changes on every read.\n\nThe key may be sent as `Authorization: Bearer `, as `X-API-Key`, or as `?token=` for tools that cannot set a header.", "operationId": "getBroadcastMatch", "parameters": [ { "$ref": "#/components/parameters/matchId" } ], "responses": { "200": { "description": "The broadcast object for this match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastObject" } } } }, "304": { "description": "Unchanged since the `ETag` you sent" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/broadcast/live": { "get": { "summary": "The broadcast object for every live match (ULTRA)", "description": "The same object as `GET /broadcast/match/{matchId}`, for every actively-live match, in one call. A ticker or a multi-match wall polls this instead of one URL per match, and it stays ONE request however many matches are live. At most 200 objects.\n\nSame 1 Hz contract, same `ETag` and `Cache-Control`, same display-form fields, same every-key-present rule. An empty `data` means nothing is live right now and is the ordinary overnight answer, not a fault.", "operationId": "getBroadcastLive", "parameters": [ { "name": "tour", "in": "query", "description": "Restrict to one tour, same vocabulary as `?tour=` elsewhere.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every live match as a broadcast object", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastObject" } }, "count": { "type": "integer" }, "served_at": { "type": "string", "format": "date-time" } } } } } }, "304": { "description": "Unchanged since the `ETag` you sent" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ws-token": { "get": { "summary": "Mint a connection token for the high-fan-out push feed (ULTRA)", "description": "Returns a short-lived signed token plus the push WebSocket URL and the channel vocabulary: `match:{match_id}` per-match streams and `slate:all` for every live score frame. Frames are the same allowlist score objects the polling endpoints return. This is a separate surface from the native `/ws` feed described above — same ULTRA gate, built for high fan-out (no shared connection ceiling), and the recommended home for continuous/production streaming.\n\nThe endpoint speaks the **Centrifugo client protocol** (v2, JSON). Easiest path: the official Python (`livetennisapi` ≥ 1.4.0) and JS (≥ 1.5.0) SDKs ship a built-in `PushStream` client — no extra dependency. Raw protocol, if you prefer your own client: (1) open a WebSocket to `ws_url`; (2) send `{\"connect\": {\"token\": \"\"}, \"id\": 1}` — the token goes INSIDE this JSON frame, never as a raw first message; (3) subscribe per channel with `{\"subscribe\": {\"channel\": \"slate:all\"}, \"id\": 2}`; (4) publications arrive as `{\"push\": {\"channel\": ..., \"pub\": {\"data\": }}}`; (5) the server's heartbeat is an empty JSON object `{}` — reply with `{}` promptly or you will be disconnected. Messages may batch several newline-delimited JSON objects. Tokens are short-lived and the connection closes around token expiry: mint a fresh token on EVERY reconnect and re-subscribe.\n\nThe `channels` object lists only channels that will actually deliver for your key right now (a channel name in this response is a promise). Where enabled server-side, additional channel families appear: `point:match:{match_id}` / `point:slate` (per-point events), listed — as `point_match` / `point_slate` in the vocabulary — only for keys whose plan carries the point surface, and `signal:match:{match_id}` / `signal:slate` (derived `break_point`, `break_point_result` and `divergence` events, and since 2026-09-12 the stoppage family: `medical_timeout_start/end`, `trainer_called/_end`, `toilet_break_start/end`, `stoppage_start/end`, `pause_start/end`). A family absent from the response will not deliver for your key right now. Deliberately separate channels: a `slate:all` subscriber asked for score states and never starts receiving events unasked. Point and signal frames are events, not states — a missed point does NOT self-correct on the next frame; recover it via `GET /matches/{matchId}/points?after_seq=` and dedup by `seq`.\n\nWITHDRAWN STATES, AND HOW TO GET ONE BACK. This feed publishes every state we accept and runs no trust deference, while `GET /matches/{matchId}/score` runs the legality gate and can serve an older state than the newest row. So a state you receive here can later be one we do not stand behind, and when that happens a `score_withdrawn` frame follows the state's own `score` frame on the same channel. Eight keys, and no replacement score:\n\n```json { \"type\": \"score_withdrawn\", \"match_id\": 4711, \"kind\": \"withdrawn\",\n \"superseded_sequence\": 118, \"reason\": \"illegal_completed_set\",\n \"safe_to_resume\": true, \"ts\": \"2026-09-25T10:00:03.108Z\",\n \"published_at\": \"2026-09-25T10:00:03.115Z\" }\n```\n\n`superseded_sequence` is the `sequence` you hold and are to discard. The state to resume from is the one on the next `score` frame, or on a fresh `GET /matches/{matchId}/score`. `kind` is `withdrawn` (discard), `deferred` (the refused state may be early and is pending the next accept, so hold it) or `withheld` (nothing publishable, `games` is null). `ts` is when the judgement was made, `published_at` when this feed was handed the frame. A given (match, `sequence`) is withdrawn at most once per publishing process and there is no replay.\n\nA consumer that was disconnected recovers the judgement from the durable record, added 2026-09-25: `GET /matches?withdrawn_since=` for the matches that had one, `GET /matches/{matchId}/withdrawals` for the whole record on a match (each row carrying the frame exactly as it went out, and the `sequence` served in the refused state's place), and `GET /matches/{matchId}/score?sequence=N` to ask about the one sequence you hold. Records are kept 90 days. The live `verdict` on the score read is the same judgement on demand, but it is recomputed over the newest state, so it stops answering for N as soon as the next state is accepted. The record does not.", "operationId": "createWsToken", "responses": { "200": { "description": "Connection token, push URL and channel vocabulary", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "expires_in": { "type": "integer" }, "ws_url": { "type": "string", "description": "The push WebSocket URL to connect to with the token." }, "channels": { "type": "object", "description": "Channel vocabulary — `match` is the per-match pattern (`match:{id}`), `slate` is the every-live-score channel (`slate:all`). A channel listed here will actually deliver for your key; one missing will not.", "properties": { "match": { "type": "string" }, "slate": { "type": "string" }, "point_match": { "type": "string", "description": "Per-match point events (`point:match:{match_id}`). Present only when the point feed is enabled server-side and the key's plan carries the point surface." }, "point_slate": { "type": "string", "description": "Every point frame (`point:slate`). Present only when the point feed is enabled server-side and the key's plan carries the point surface." } } } }, "example": { "token": "eyJhbGciOi...", "expires_in": 3600, "ws_url": "wss://api.livetennisapi.com/connection/websocket", "channels": { "match": "match:{match_id}", "slate": "slate:all" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/UpgradeRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Direct API key: Authorization: Bearer " }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "parameters": { "matchId": { "name": "matchId", "description": "The match id. Every match route shares ONE id space, so the same value works everywhere `matchId` appears.\n\nGet it from any match list, where it is the `id` field of each match object:\n`GET /matches?status=live` (in progress), `GET /matches?status=upcoming` or `GET /fixtures` (scheduled), `GET /matches?status=completed` or `GET /history/matches` (finished).\n\nIds are stable for the life of a match, so one captured before it starts still resolves after it finishes.\n", "in": "path", "required": true, "schema": { "type": "integer" } }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, "offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, "playedFrom": { "name": "from", "in": "query", "required": false, "description": "Earliest play date, `YYYY-MM-DD` or an ISO-8601 UTC datetime. A bare date covers that whole day. An unparseable value is a 400, never a silently unfiltered 200.", "schema": { "type": "string" } }, "playedTo": { "name": "to", "in": "query", "required": false, "description": "Latest play date, same formats as `from` (a bare date includes everything played that day). `from` after `to` is a 400.", "schema": { "type": "string" } }, "tour": { "name": "tour", "in": "query", "description": "Restrict results to one tour. Each value covers its singles and doubles draws, so `atp` includes ATP doubles and `juniors` covers the boys' and girls' Grand Slam draws. Omit for all tours. An unrecognised value is a 400 rather than a silent pass-through, so a caller never receives a tour it did not ask for. Applied before pagination, so `meta.count` reflects the filtered set.", "schema": { "type": "string", "enum": [ "atp", "wta", "challenger", "itf", "juniors" ] } }, "draw": { "name": "draw", "in": "query", "schema": { "type": "string", "enum": [ "singles", "doubles" ] }, "description": "Draw filter (added 2026-08-18) — the axis the tour filter deliberately collapses; the two compose (`?tour=itf&draw=doubles` is the ITF doubles slice). Same vocabulary as the `draw` field on Match, decided by the same shared definition, so filter and field cannot disagree. A row whose draw is null — a team tie, or no stated event type and no doubles-team participant — matches NEITHER value: null is an answer, not a wildcard. Two honesty notes: on /tournaments the answer comes from the event type alone (a tournament row has no participants to supply the doubles-team evidence matches have), and draw=doubles alone also returns mixed and exhibition doubles that no tour value reaches. An unknown value is a 400 bad_draw with the allowed values." }, "player": { "name": "player", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "maxItems": 50 }, "explode": true, "description": "Filter to matches where this player id is EITHER participant. Repeatable (max 50 ids); multiple values return the deduplicated union. An unknown id returns an honest empty list, not an error; a non-integer value is a 400 `bad_request`. Before 2026-08-03 this parameter was accepted and silently ignored — treat any integration written against that behaviour as unfiltered." }, "tournamentId": { "name": "tournament_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,20}$" }, "description": "Filter to one tournament — exact match on the stable numeric id every match row publishes as `tournament_id` and `/tournaments` publishes as `id`, so the value round-trips straight off any response. Works on `/matches` (every status) and `/history/matches`, and composes with every other filter: `?tour=atp&draw=singles&tournament_id=1217` is one slam's men's singles, where `?tour=` alone still mixes concurrent events during a slam fortnight. There is no separate edition or occurrence id: `tournament_id` is stable across seasons, so one EDITION is `tournament_id` plus a `from`/`to` window around its dates. Matches whose `tournament_id` is null (a tournament not yet in the catalogue) never match this filter; a date-window listing without it still returns them. Unknown-but-numeric ids return an empty list, not an error; a non-numeric value is a 400 `bad_tournament_id`." }, "tier": { "name": "tier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tier filter (added 2026-09-22): comma-separated exact values from the closed tier vocabulary (`?tier=wta_125`, `?tier=itf_w35,itf_w50,itf_w75`, `?tier=challenger_75,challenger_100`). Selects matches whose `tier` field carries one of the values — the level the tournament was played at in the MATCH'S season, read from the same per-season table, so filter and field cannot disagree. A match whose `tier` is null matches no value. Composes with every other filter (`?tour=challenger&gender=women&tier=wta_125` and `?tier=wta_125` select the same rows; `?tier=challenger_125&draw=doubles` is a slice `tour=` alone cannot make). Available on `/matches` (every status) and `/history/matches`. `/tournaments` takes `?tier=` as well, reading the CURRENT season rather than a match's, and states that difference on its own parameter. Unknown value → 400 `bad_tier` with the offending values in `bad` and the full vocabulary in `allowed`." }, "withdrawnSince": { "name": "withdrawn_since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ULTRA. A DIFFERENT LISTING, not a filter on the match page: the match ids with a WITHDRAWN score state at or after this instant, newest first, one row per match as `{ match_id, withdrawals, last_withdrawn_at }` with an exact `meta.total` and `limit` / `offset` paging. A UTC date (YYYY-MM-DD) or an ISO-8601 UTC datetime. This is how a stream consumer that was disconnected finds which matches to ask `GET /matches/{matchId}/withdrawals` about. It takes no other parameter beside `limit` and `offset` — `status`, `updated_since`, the date range and every match filter are `400 bad_withdrawn_since`, as is an unparseable instant. Records are kept 90 days from the withdrawal." }, "sequence": { "name": "sequence", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The `sequence` YOU HOLD for this match, from the push feed, the WebSocket or an earlier read. `verdict` is recomputed on every read over the newest state, so on its own it says nothing about a sequence that was withdrawn before the next state landed. With `?sequence=N`, and only when the read carries no verdict of its own, `verdict` answers for N from the durable withdrawal record: `kind: withdrawn` with the recorded reason when we discarded that state, null when we never did. Only a discarded record is re-asserted this way; a `deferred` state may since have been corroborated and a `withheld` read described that moment's scan, so neither is. A verdict the read produces itself always wins, because it describes the state being served. Every other field still describes the served state. A non-integer is `400 bad_sequence`, never accepted and ignored." }, "updatedSince": { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CHANGE FEED. A UTC date (YYYY-MM-DD) or ISO-8601 datetime. Returns the rows whose `updated_at` is at or after it, OLDEST FIRST, with `meta.next_cursor` and `meta.watermark`. Poll from `meta.watermark`, not from your own clock — it trails the server by 5s on purpose, because a row committed while your request was being served can carry a timestamp below your `now` and still not be in your result. Overlap ~60s and dedupe by `id`; the feed is at-least-once by design. CANNOT be combined with `from`/`to` (400 `bad_updated_since`): those filter when a match was PLAYED and sort by play time, this filters when its row CHANGED, and a change cursor cannot resume a play-time ordering. Not accepted with `status=cancelled` (400 `bad_request`). Anything unparseable is a 400, never accepted and ignored. A physically DELETED row can never appear in the feed; cancellations, walkovers and withdrawals are status CHANGES and do appear." }, "cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Echo back `meta.next_cursor` to fetch the next page of a change feed. Opaque — do not parse it, its contents will change. Supplies both the floor and the tie-break position, so it replaces `updated_since` on follow-up pages rather than accompanying it." }, "hasAnalysis": { "name": "has_analysis", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return only matches that DO (`true`) or do NOT (`false`) have model analysis, matching the `has_analysis` flag each row carries (filter added 2026-09-14, documented here 2026-09-20). Omit for both. Anything other than true/false is a 400 `bad_has_analysis`, never a silently ignored filter. These are the matches `/matches/{matchId}/analysis` can serve; every other id answers 404 `no_analysis`. The misses are structural rather than transient — analysis is produced only for a match carrying a mapped market — so a caller polling the unanalysed half is asking a question whose answer can never become yes. Filter the slate with this instead." }, "hasMarket": { "name": "has_market", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return only matches that DO (`true`) or do NOT (`false`) have a mapped match-winner market, matching the `has_market` flag each row carries (added 2026-09-15). Omit for both. Anything other than true/false is a 400 `bad_has_market`, never a silently ignored filter. These are the matches `/history/matches/{id}/prices` and `/matches/{id}/prices` can serve; every other id answers 404 `no_market`. Measured 2026-09-15: 3,718 of the 9,741 matches completed since 2026-08-16 (38%) had a price tape." }, "isQualifying": { "name": "is_qualifying", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return only matches in the QUALIFYING draw (`true`) or only those the source states are not (`false`), matching the `is_qualifying` flag each row carries (field added 2026-08-12, filter added 2026-10-02). Omit for both. Anything other than true/false is a 400 `bad_is_qualifying`, never a silently ignored filter.\nTHIS IS THE ONLY WAY TO SPLIT THE TWO DRAWS, and the reason is in the `is_qualifying` field description: the two are routinely carried under ONE tournament name with ONE round vocabulary, so `tournament`, `tournament_id`, `round` and `round_code` all read main-draw for a qualifying match. Do not filter on the round text.\nTHREE-VALUED, so this filter is too: a row whose flag is `null` (no source has ever stated it) matches NEITHER value and is returned only when the filter is omitted. `null` is an answer, not a `false` — returning it under `is_qualifying=false` would assert \"main draw\" on the strength of nothing. Measured 2026-10-02 over completed matches: the flag is stated on 98.9% of the last 30 days and 98.3% of 2026 outside the UTR circuit, where it is mostly unstated (1,695 of the 1,831 unstated rows in the last 30 days are UTR)." }, "gender": { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "men", "women" ] }, "description": "Return only men's or only women's matches, matching the `gender` field each row carries (added 2026-09-09, documented here 2026-10-02). Omit for both. Anything other than men/women is a 400 `bad_gender`, never a silently ignored filter.\nIt exists because `?tour=` deliberately collapses: `challenger` is ATP Challenger AND WTA 125, and `itf` and `juniors` are both sexes — so without this there is no way to ask for men's Challenger at all. A row whose `gender` is `null` (mixed doubles, a team tie) matches NEITHER value, the same contract as `?draw=` and `?is_qualifying=`.\n bad_points_complete, bad_combination, points_read_disabled, bad_after_seq, bad_has_market, no_market, points_disabled," }, "country": { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 3 }, "description": "Filter to matches where EITHER participant's `player.country` equals this lowercase 3-letter code — the same vocabulary the Player object returns (IOC-style codes, e.g. `ned`, `sui`, `gre`; NOT ISO-3166). Players with no recorded country never match, so a country filter excludes unknown-nationality matches rather than guessing. A value that is not 3 letters is a 400 `bad_country`." } }, "responses": { "BadRequest": { "description": "Bad query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, unknown, or disabled credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpgradeRequired": { "description": "Your tier doesn't unlock this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such resource, or no data yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MatchGone": { "description": "The match id existed and was merged into another match record (since 2026-09-05). The body is `MatchMerged`, not `Error`: it carries a forwarding address, which is the whole point of answering 410 rather than 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchMerged" } } } }, "PlayerGone": { "description": "The player id existed and was merged into another player record, or was retired with no successor. The body is `PlayerMerged`, not `Error`: it carries a forwarding address, which is the whole point of answering 410 rather than 404. An id that was NEVER issued keeps its 404 — a 410 would assert it once existed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerMerged" } } } }, "RateLimited": { "description": "Rate limit exceeded (Retry-After header present). Three body shapes, told apart by `error` and `scope`: the per-MINUTE limit (`rate_limited`, with `upgrade_url`, `tier` and `price` naming the next tier up); the per-DAY quota (`rate_limited` with `scope: \"day\"`, `limit_per_day`, and `resets_at` — the absolute ISO instant the daily window resets); and `abuse_throttled` with `retry_at_epoch` — a 24-hour block applied to clients that keep hammering far past their cap, which a well-behaved retry loop never sees. Fix the loop rather than retrying through it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "PlayerNotFound": { "type": "object", "description": "The 404 body for /players/{playerId} and its two stoppage aliases. `detail` and `see` appear ONLY when the requested id resolves in the results-archive person registry — the signpost across the two id spaces. They are absent for an id we simply do not hold. The person is never named here: the archive is History-gated and this route is not.", "properties": { "error": { "type": "string", "enum": [ "not_found" ] }, "detail": { "type": "string", "description": "Present only when the id is a corpus person id." }, "see": { "type": "string", "description": "Present only when the id is a corpus person id — the archive lookup that reads it, e.g. `/api/public/v1/history/archive/players?id=104925`." } }, "required": [ "error" ] }, "MatchMerged": { "type": "object", "description": "The 410 GONE body for a match id that was merged into another match record. Distinct from `Error` because it carries a forwarding address.", "properties": { "error": { "type": "string", "description": "Always `merged`." }, "merged_into": { "type": [ "integer", "null" ], "description": "The id that absorbed this one — re-point your records at it. Null means the forwarding target is unknown: nothing to forward you to, drop the id. On a merge chain this is the END of the chain, never an intermediate id that would 410 in turn." }, "merged_at": { "type": "string", "format": "date-time", "description": "When THIS id stopped existing (UTC). On a chain it is the FIRST hop — the moment your copy of this id went stale." }, "detail": { "type": "string", "description": "Human-readable explanation; differs for a merge and for a retirement so the two are distinguishable without parsing prose." } } }, "PlayerMerged": { "type": "object", "description": "The 410 GONE body for a player id that was merged into another player record, or retired outright. Same shape as `MatchMerged` and the same reasoning: a redirect would rewrite the identity inside your warehouse without you seeing it, so the id is answered rather than forwarded.", "properties": { "error": { "type": "string", "description": "Always `merged`." }, "merged_into": { "type": [ "integer", "null" ], "description": "The id that absorbed this one — re-point your records at it. Null means the player was RETIRED with no successor: nothing to forward you to, drop the id. On a merge chain this is the END of the chain, never an intermediate id that would 410 in turn." }, "merged_at": { "type": "string", "format": "date-time", "description": "When THIS id stopped existing (UTC). On a chain it is the FIRST hop — the moment your copy of this id went stale." }, "detail": { "type": "string", "description": "Human-readable explanation; differs for a merge and for a retirement so the two are distinguishable without parsing prose." } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Stable machine-readable code, e.g. bad_date, bad_coverage, bad_sequence, bad_points, bad_points_complete, bad_combination, points_read_disabled, bad_after_seq, bad_changed_since, bad_restated_since, points_disabled, bad_period, bad_year, bad_format, bad_tour, bad_tier, bad_country, ambiguous_name, not_charted, not_found, no_analysis, no_market, upgrade_required, rate_limited, abuse_throttled." }, "detail": { "type": "string", "description": "Human-readable explanation, when one adds anything." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "On a rejected enumerated parameter, the values that would have been accepted (e.g. the coverage vocabulary for bad_coverage)." } } }, "ListMeta": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" }, "total": { "type": [ "integer", "null" ], "description": "Size of the whole filtered set. Null when it cannot be counted cheaply." }, "has_more": { "type": "boolean", "description": "More results exist beyond this page. Read this rather than comparing count to limit. For a complete enumeration of a filtered set, page `offset` forward by `limit` until this is false; on `completed`/`cancelled` listings `total` is null and this is the only end-of-data signal." }, "next_cursor": { "type": [ "string", "null" ], "description": "Change-feed only (`?updated_since=` / `?cursor=`). Opaque token to pass back as `?cursor=`. Null means you are caught up — stop paging and switch to polling from `watermark`." }, "watermark": { "type": [ "string", "null" ], "format": "date-time", "description": "Change-feed only. The floor to use on your NEXT poll. Deliberately trails the server clock by 5s so a row committed during this request cannot fall through the gap." } } }, "Score": { "type": "object", "description": "One state at one instant. ULTRA adds win_probability_p1 + danger. Order and de-duplicate on `sequence`, never on `timestamp`.", "properties": { "sets": { "type": "array", "items": { "type": "integer" } }, "games": { "type": [ "array", "null" ], "description": "[games_p1, games_p2]; each a per-set list. NULL means WITHHELD — we hold no state for this match we can stand behind (see `detail`); it never means 0-0, and an empty array is never used to mean \"unknown\". A deciding set played as a 10-point MATCH TIEBREAK (super-tiebreak) carries the BREAKER's score in its slot WHILE IT IS BEING PLAYED — `[[6,4,10],[4,6,5]]` is `6-4 3-6 [10-5]`, not a 10-game set — and `is_tiebreak` is true then. Once the breaker is over that set is often published as a one-game `1-0`: take the match winner from `sets`, never from the deciding set's games.", "items": { "type": "array", "items": { "type": "integer" } } }, "points": { "type": "array", "items": { "type": "string" } }, "server": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "is_tiebreak": { "type": "boolean", "description": "The current game is a tiebreak. On a DECIDING set played as a 10-point match tiebreak this is true for the whole set, whose `games` slot holds the breaker." }, "win_probability_p1": { "type": [ "number", "null" ] }, "danger": { "type": [ "number", "null" ] }, "win_probability_p1_model": { "type": [ "number", "null" ], "description": "ULTRA, since 2026-09-12. The same model read computed WITHOUT the market-prior anchor — a probability no market price touched. Equals win_probability_p1 on a match the anchor does not apply to, and also on some rows of an anchored match (the anchor shifts the pre-match hold rates, which enter the engine snapped to a 0.01 grid, so a shift smaller than a grid step often solves to an identical value); the per-row test is win_probability_p1 != win_probability_p1_model. Null on rows stamped before it existed (never back-filled)." }, "win_probability_meta": { "type": [ "object", "null" ], "description": "ULTRA, since 2026-09-12. Our own model-regime identifier (`model_version`), the UTC instant the two probabilities were generated (`generated_at`), whether the anchor applies to this MATCH (`market_anchored` — per match, not per row) and, since 2026-09-15, whether it moved THIS ROW's win_probability_p1 away from the twin (`anchor_effective`). Null on rows stamped before it existed. SEGREGATING A RECORDED CORPUS — cut on the CLOCK, not on the version string. Two changes moved published live probabilities before `model_version` reflected them, so split a corpus on `generated_at` (or the row's `timestamp`) at these two instants: 2026-08-18T08:29:28Z, when the over-inclusive deciding-set rule for lower-tier singles began (some final sets priced as a race-to-ten breaker), and 2026-09-16T07:59:54Z, when the draw-based rule replaced it (main-draw singles priced as a full set — a move of up to 0.20 on affected deciding-set states). `model_version` is NOT a safe discriminator across the second boundary: the `+itfdraw-2026-09-16` suffix first appears on rows generated 2026-09-17T05:04:25Z, 21 h 04 m AFTER the rule itself landed, and in that gap 33,510 states across 351 matches (9,719 states over 113 matches at the ITF M15/W15/W35 levels the rule governs) were computed under the CORRECTED rule while still carrying `markov-population-2026-08-23`. Cutting on the version string — or on a whole-day boundary — mislabels exactly those rows; cutting at 2026-09-16T07:59:54Z does not. Measured against production 2026-09-19. CORRECTION (2026-09-19): both instants were first published, the same day, THREE HOURS LATE — 2026-08-18T11:29:28Z and 2026-09-16T11:02:00Z — because the switch times were read off a column stored in local wall time and labelled UTC. The instants above are the corrected UTC ones. If you cut a corpus on either of the old values, re-cut: everything in the three hours before them is on the wrong side. Earlier than that there is no stamp to cut on at all: no row generated before 2026-09-12T12:08:17Z carries `model_version` or `generated_at`, and the bulk tape packages have no version column, so for those the row `timestamp` is the only discriminator. The `model_version` on an analysis profile (`ModelProfile`) is a different identifier for a different object — the forecast's prompt scaffold — and does not apply to score rows.", "properties": { "model_version": { "type": "string", "example": "markov-population-2026-08-23", "description": "The model regime that produced this row: engine family, calibration key scheme and — since 2026-09-17 — every pricing rule in force, as a `+…` suffix. It is not a safe cut for a recorded corpus across the 2026-09-16 boundary; see this object's description for the two instants to segregate on." }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "market_anchored": { "type": "boolean", "description": "The market-prior anchor applies to this match: a two-sided pre-match price and a pre-play first score gave the model a shift to its pre-match prior. Per match, not per row." }, "anchor_effective": { "type": [ "boolean", "null" ], "description": "Since 2026-09-15. This row's win_probability_p1 differs from win_probability_p1_model, i.e. the anchor moved this value. Null when either probability is null." } } }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Our clock, not the court's: stamped in our process when the state was accepted (the same step that assigns `sequence`), then refreshed — at most every 8 s — while the owning source keeps re-asserting the unchanged state, so on a live read it is usually the last-assertion instant, not the accept instant. Never an upstream observation time, never a source's own clock. NOT an ordering key — use `sequence`; for the accept instant use `accepted_at`." }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Since 2026-09-15. The instant we accepted this state (UTC): stamped once at insert, never refreshed by a re-assertion — the clock to difference a latency study against. Present on live score reads and push frames, and since 2026-09-24 on history-tape rows too (this description said \"absent on history-tape rows\" until 2026-09-25, which had been wrong since the tape started carrying it — see `HistoryTapeRow.accepted_at`). Null on the archive fallback of a retention-trimmed completed match." }, "sequence": { "type": [ "integer", "null" ], "description": "Per-match accept counter for this state: 1, 2, 3, … in the order we accepted states for THIS match, gapless within a match — higher is later, equal is the same state re-served, and a gap between two reads is exactly that many missed updates. On /matches/{matchId}/score it moves BACKWARDS in two cases only: we withdrew a state we cannot stand behind and re-served the last good one, or the read deferred to a strictly higher-trust source's fresh state (about 1% of live reads, measured 2026-09-15). On the push feed and the native WebSocket it only ever rises. Null on states that predate the counter — never fabricated. Present on live score reads AND, since 2026-09-26, on history-tape rows too — see `HistoryTapeRow.sequence`. This description said \"absent on history-tape rows, which are already served in order\" until then, and the reasoning was the gap: being served in order does not let you resolve the `replaced_by_sequence` that `GET /matches/{matchId}/withdrawals` hands you, which is a pointer AT a counter and not a position in a list. Since 2026-09-24 a set completion that does not end the match is assigned a sequence only once confirmed — the same source keeps presenting the completed set for 10 s or more, a source at least as trusted presents it, or the same source shows play continuing inside the new set. A live scoring display can render the set-ending frame ON set point, before the point is decided, and step back when it is not won; the unconfirmed frame is now never stored, so no sequence ever carries it and nothing is published as provisional. Until a frame is confirmed every surface keeps serving the set-point state; one nobody confirms within 120 s is discarded. A set completion that ENDS the match is exempt — it follows the completion rules instead. Measured over the 30 days to 2026-09-24 this adds a median 10 s between the point and the published set-end, and on a feed that does not re-present states the set-end lands with the first point of the next set (90th percentile 133 s). It does not cover a set genuinely won and then corrected on court, which can still be published and rewound." }, "age_seconds": { "type": [ "integer", "null" ], "description": "Seconds since the score CONTENT last changed (not since we last polled) — it keeps rising between points. Null = change-clock unknown for this row, never \"fresh\". Always null on the archived final that `/matches/{matchId}/score` serves for a settled match whose live rows were retired (since 2026-09-20): no clock is claimed for a state nobody watched." }, "stale": { "type": "boolean", "description": "Our own staleness verdict on age_seconds for a LIVE match (threshold currently 120s). Always false on a completed match: its last state is final, not stale." }, "observed_age_seconds": { "type": [ "integer", "null" ], "description": "Seconds since ANY of our sources last CONFIRMED this state — the insert itself, the owning source re-asserting it, or an independent source agreeing with it. The \"is anyone still watching\" clock, next to `age_seconds`, the \"has anything happened\" clock: a long age_seconds with a small observed_age_seconds is a changeover or set break, not a stall. Null = unknown: no observation clock stored on the row, or the archive fallback on a retention-trimmed completed match (where age_seconds and sources_count are null too). Absent on history-tape rows." }, "sources_count": { "type": [ "integer", "null" ], "description": "How many DISTINCT sources inserted or independently confirmed this match's state in the last 60 seconds (our public source window). A count, never a name; it counts sources we accepted a state from or that agreed with the stored state, so it can under-count and never over-counts. 1 is ordinary; 0 on a live match past a full minute means nobody we accepted a state from, or who agreed with the stored state, has reported it in the last 60 seconds; 0 on a completed match is normal. Null = unknown (a read blip, or the archive fallback). Present wherever observed_age_seconds is." }, "changing_sources_count": { "type": [ "integer", "null" ], "description": "Since 2026-09-24. How many DISTINCT sources CHANGED this match's score in the last 300 seconds — sources that inserted a new state, counted on the content clock alone. A source re-asserting an unchanged state is not counted, which is the difference from sources_count: a feed stuck re-sending its last state keeps sources_count at 1 for as long as the echo lasts and keeps this at 0. The window is wider than sources_count's on purpose, because a point lands every 30-60 s and a changeover is about 90 s. A cross-confirmation is agreement, not a change, so this can read below sources_count and never above it. 0 on a live match past five minutes means nobody moved the score in that time; 0 on a completed match is normal. Null = unknown (a read blip, or the archive fallback). A count, never a name. Present wherever sources_count is." }, "corroborated": { "type": [ "boolean", "null" ], "description": "Since 2026-09-24. Has an INDEPENDENT source vouched for THIS EXACT state? True when a source other than the one that wrote this state has since presented us the same state; false when none has, including a brand-new state nobody has had a chance to agree with yet. This is the field to gate a SET-END on. The two counts above are window measures over the match and say nothing about the state in front of you, so a set completion only one source has announced can sit beside a perfectly healthy sources_count — and a set-end is the one state whose correction changes a result rather than a number. EVIDENCE, NOT PROOF: a vouched state can still be corrected, so read corroborated_age_seconds beside it and treat a vouch that is younger than the state it vouches for as the weaker signal it is. When we do take a state back the `sequence` goes down and `verdict` says so. Null = unknown (the archive fallback on a retention-trimmed completed match, where age_seconds and sources_count are null too). A yes/no, never a name. Present wherever sources_count is." }, "corroborated_age_seconds": { "type": [ "integer", "null" ], "description": "Since 2026-09-24. Seconds since that independent vouch. Null when corroborated is false (nobody has) or null (unknown). Compare it with age_seconds: a vouch OLDER than the state means somebody agreed with this state after it was published; a vouch younger than the state is one that landed late." }, "detail": { "type": "string", "description": "Present only when something is withheld — plain-language reason, e.g. a null `games` array." }, "verdict": { "type": [ "object", "null" ], "description": "Why this read is not the newest state we judged (since 2026-09-23). Null on an ordinary read. Otherwise the legality gate refused a state a stream had already published, and this says which and why. `superseded_sequence` is the `sequence` of the refused state, the value a stream consumer holds. `reason` is the gate's slug. `kind` is `withdrawn` (discard the refused state and resume from the served one), `deferred` (it may be early and is pending the next accept) or `withheld` (nothing publishable, `games` is null). `safe_to_resume` is true exactly when `kind` is `withdrawn`. The push feed, the WebSocket and webhooks announce the same judgement as a `score_withdrawn` frame naming the same sequence, so a stream consumer never has to poll to learn a state was taken back. That frame carries `type`, `match_id`, `kind`, `superseded_sequence`, `reason`, `safe_to_resume`, `ts` and `published_at`, and no replacement score: resume from the next `score` frame or from a fresh read. Since 2026-09-25 this field also answers for a sequence you name with `?sequence=N`, from the durable record served by `GET /matches/{matchId}/withdrawals` — which is how a consumer that missed the frame recovers it.", "properties": { "kind": { "type": "string", "enum": [ "withdrawn", "deferred", "withheld" ] }, "superseded_sequence": { "type": [ "integer", "null" ] }, "reason": { "type": "string" }, "safe_to_resume": { "type": "boolean" } } } } }, "Incident": { "type": "object", "description": "One published data-quality incident. Every field is written as part of a release, so the record does not change between releases.", "properties": { "id": { "type": "string", "description": "Stable slug, e.g. `deciding-set-level-rule-2026-08-18`." }, "kind": { "type": "string", "description": "The incident's family. Current values are `pricing_rule`, `version_stamp`, `field_orientation` and `field_repair`. The live list is in `meta.kinds`." }, "title": { "type": "string" }, "window_utc": { "type": "object", "description": "When the incident applies. Every instant is UTC, and `basis` says what the window was read from.", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" }, "basis": { "type": "string" } } }, "rule_before": { "type": "string" }, "rule_after": { "type": "string" }, "defect": { "type": "string", "description": "What was wrong, with the measurement behind it." }, "affected_surfaces": { "type": "array", "description": "The endpoints and fields the incident reached.", "items": { "type": "string" } }, "how_to_tell": { "type": "string", "description": "How to separate an affected row from a clean one, in your own copy of the data." }, "corrections": { "type": "object", "description": "Whether the published values were restated. When `available` is false, `detail` says what to do instead.", "properties": { "available": { "type": "boolean" }, "detail": { "type": "string" } } }, "matches": { "type": "object", "description": "Whether a per-match list can be derived exactly. `note` names the rows that cannot, and `url` is the export when `derivable` is true.", "properties": { "derivable": { "type": "boolean" }, "note": { "type": "string" }, "url": { "type": "string" } } } } }, "PlayerStoppage": { "description": "One row of GET /players/{playerId}/stoppages — an in-match stoppage on one of the player's matches, or a match the player did not finish. Stoppage rows carry `score_at`, `duration_seconds` and `reason`; outcome rows carry `final_score` when a score row exists. Never inferred except `pause` (source_stated false).", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "medical_timeout", "trainer_called", "toilet_break", "pause", "stoppage", "retirement", "walkover" ] }, "at": { "type": "string", "format": "date-time", "description": "UTC instant of the stoppage (the source's own instant) or of the recorded outcome." }, "match_id": { "type": "integer" }, "tournament": { "type": [ "string", "null" ] }, "opponent": { "type": [ "object", "null" ], "description": "The other side of the match; null when unknown.", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "score_at": { "type": "object", "description": "Stoppage rows only — the score at the stoppage.", "properties": { "sets": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "games": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } }, "points": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] } } } }, "final_score": { "type": "object", "description": "Outcome rows only, when a score row exists — sets and games of the newest score row.", "properties": { "sets": { "type": "array", "items": { "type": "integer" } }, "games": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } } } }, "attribution": { "type": "string", "enum": [ "player", "match" ], "description": "`player` — the source named this player's side (or the result names them as the non-winner); `match` — the source stated the stoppage for the match without a side, so the row appears in both players' lists." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Seconds to the matching end row; null when no end row was recorded and on outcome rows." }, "source_stated": { "type": "boolean", "description": "True when a scorer, umpire, live-scoring state or result stated it; false only on `pause` (clock-inferred)." }, "reason": { "type": "string", "description": "Stoppage rows only — the stated reason; `unknown` when only a flag reached us." } } }, "PlayerStoppagesMeta": { "type": "object", "properties": { "player_id": { "type": "integer" }, "window": { "type": "object", "description": "The bounds actually applied, UTC.", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } } }, "kinds": { "type": "array", "description": "The kinds this response was filtered to.", "items": { "type": "string" } }, "counts": { "type": "object", "description": "Per selected kind, the number of rows over the WHOLE window (not the page).", "additionalProperties": { "type": "integer" } }, "latest_medical_timeout": { "oneOf": [ { "$ref": "#/components/schemas/PlayerStoppage" }, { "type": "null" } ], "description": "The newest medical timeout in the window, whatever the page or kind filter; null when none." }, "previous_medical_timeout": { "oneOf": [ { "$ref": "#/components/schemas/PlayerStoppage" }, { "type": "null" } ], "description": "The one before it; null when fewer than two." }, "record_starts": { "type": "object", "description": "How far back each family is recorded — read before trusting a long window.", "properties": { "stoppages": { "type": "string", "description": "2026-09-12 — no stoppage row exists before this day." }, "outcomes": { "type": [ "string", "null" ], "description": "Date of the oldest match with a stated winner (the field an outcome row needs)." } } }, "note": { "type": "string", "description": "In-match stoppages and match outcomes only; no off-court injury record." }, "limit": { "type": "integer" }, "count": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as `?before=`; null when the window is exhausted." } } }, "Player": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "tour": { "type": [ "string", "null" ], "description": "The record's OWN tour, which is NOT the `tour` filter vocabulary. It is granular (`juniors_boys`, `juniors_girls`, `challenger_men`) where the filter is grouped (`juniors`, `challenger`), and a doubles team reports it UPPERCASE (`ATP`) where an individual reports lowercase (`atp`). Treat it as an opaque string; do not parse it into the filter enum." }, "country": { "type": [ "string", "null" ] }, "ranking": { "type": [ "integer", "null" ], "description": "Official singles ranking POSITION (the ordinal: 1, 25, 100) — never points, seed, race, UTR, Elo or a doubles rank. Men from the official ATP table, women from the WTA table, chosen by the player (a Challenger or ITF man who holds an ATP ranking carries it here). Refreshed from the standings ahead of each match the player has with us; a player who has not played recently keeps their last refreshed position. `null` when no ranking is held (doubles teams, most ITF/junior-only players). Always the CURRENT record, even on historical matches — use `/rankings?as_of=` for the rank in force on a date." }, "ranking_points": { "type": [ "integer", "null" ], "description": "Points on the same official table, refreshed with `ranking`." }, "ranking_movement": { "type": [ "string", "null" ], "enum": [ "up", "down", "same", null ] }, "hand": { "type": [ "string", "null" ], "enum": [ "R", "L", null ] }, "backhand": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "birthday": { "type": [ "string", "null" ], "format": "date" }, "is_doubles_team": { "type": "boolean" }, "data_completeness": { "type": "object", "description": "How much biographical detail is known for this player, so a consumer can distinguish \"not in the feed\" from \"not yet fetched\" without probing. Present on every player in a match payload. Lower tours carry far less of it than main tour.", "properties": { "known": { "type": [ "integer", "null" ], "description": "Fields populated, of `of`. NULL on a doubles team, where per-player biography does not apply — distinct from `0`, which means the fields apply and none are known. Do not decode this into a non-nullable integer." }, "of": { "type": [ "integer", "null" ], "description": "Fields considered. NULL on a doubles team, as for `known`." }, "missing": { "type": "array", "description": "Names of the unpopulated fields, e.g. [\"backhand\", \"hand\"].", "items": { "type": "string" } }, "note": { "type": "string", "description": "Present only when the object is not applicable, explaining why (e.g. a doubles team)." } } }, "stats": { "type": "object", "description": "Single-player endpoint only", "properties": { "ratings": { "type": [ "object", "null" ] }, "ratings_as_of": { "type": [ "string", "null" ], "format": "date", "description": "The date (UTC) the `ratings` block was last refreshed (added 2026-09-10). The current Elo is refreshed every week from the published rating tables; read this before treating a rating as this week's. Null when there is no rating." }, "season": { "type": [ "array", "null" ] } } } } }, "Match": { "type": "object", "properties": { "id": { "type": "integer" }, "tournament": { "type": "string" }, "tour": { "type": [ "string", "null" ], "enum": [ "atp", "wta", "challenger", "itf", "juniors", null ], "description": "The tour, in the SAME vocabulary the `tour` query filter accepts — both are derived from one registry, so a match selected by `?tour=X` always carries that value in `tour`. Null when the feed never stated a tour or the event type has no public tour name (exhibitions, team and mixed events) — never guessed. Safe to group and filter on; never parse the tournament name for this." }, "tournament_id": { "type": [ "string", "null" ], "description": "Stable tournament identity — one id per tournament × event type, stable across seasons. Joins `GET /tournaments/{tournamentId}`. Null when the tournament is not in the catalogue at all (UTR events), and on the small residue of matches discovered through a secondary source whose tournament name could not be matched to exactly one catalogue edition — never guessed. Measured over August 2026 terminal matches: ATP 1 of 531 and WTA 3 of 513 null; ITF about 2.5% after the 2026-09-04 backfill (was ~25%); UTR 100%. (Edge case — a match mislabelled as qualifying by the feed has its id re-pointed to the main-draw tournament when detected, so the id can change once, early, in that direction only.)" }, "tier": { "type": [ "string", "null" ], "enum": [ "grand_slam", "atp_finals", "atp_1000", "atp_500", "atp_250", "next_gen_finals", "united_cup", "davis_cup", "olympics", "laver_cup", "wta_finals", "wta_elite_trophy", "wta_1000", "wta_500", "wta_250", "wta_125", "bjk_cup", "challenger_175", "challenger_125", "challenger_100", "challenger_75", "challenger_50", "itf_m15", "itf_m25", "itf_w15", "itf_w25", "itf_w35", "itf_w40", "itf_w50", "itf_w60", "itf_w75", "itf_w80", "itf_w100", "juniors", "utr", "exhibition", null ], "description": "The level the tournament was played at IN THIS MATCH'S SEASON (added 2026-09-22) — the official category as the tour publishes it, in a closed vocabulary: `grand_slam`; the ATP levels (`atp_finals`, `atp_1000`, `atp_500`, `atp_250`, `next_gen_finals`); the WTA levels (`wta_finals`, `wta_elite_trophy` — last held 2023 — `wta_1000`, `wta_500`, `wta_250`, `wta_125`); the ATP Challenger levels (`challenger_175` … `challenger_50`); the ITF World Tennis Tour categories (`itf_m15`, `itf_m25`, `itf_w15` … `itf_w100` — the 2023 women's categories `itf_w25`/`itf_w40`/`itf_w60`/`itf_w80` are kept as printed that season, not mapped onto the 2024 ladder, because the level a match was played at is a fact about that season); the team events (`united_cup`, `davis_cup` and `bjk_cup` in every group and stage, `laver_cup`, `olympics`); `juniors`; `utr`; and `exhibition` (no ranking points — Hopman Cup class). Same vocabulary as the `?tier=` filter, read from the same per-season table, so filter and field cannot disagree. Resolved by the MATCH'S season (the calendar year of `scheduled_time`), never copied from the tournament row: a tournament keeps one `tournament_id` across seasons while its level moves — Dallas was `atp_250` in 2023 and 2024 and `atp_500` from 2025, so a 2024 Dallas match reads `atp_250` and a 2025 one `atp_500` under the same id. Coverage of the 2023–2026 seasons was verified event by event against the official calendars (99.1% of tournament-seasons resolved; the rest are deliberately null — the Asian Games tennis event, which no tour lists). A new event may read null for a short while after its first match until its tier is resolved. Null when nothing we hold names the level — never guessed; null is \"we do not know\", never a level. `category` on `/tournaments` is unchanged and remains the coarse class (`challenger`, `itf`, `atp_250` …); read this field for the level." }, "tier_source": { "type": [ "string", "null" ], "enum": [ "calendar", "name", "wikipedia", "resolver", null ], "description": "How `tier` was established (added 2026-09-22): `calendar` = the official per-season tour calendar named the level (ATP tour and Challenger calendars, the WTA tournament list); `name` = an unambiguous name rule (the ITF category is in the event's official name — `M25 …`, `W35 …` — team and UTR events are named as such, and the Slam junior draws and exhibitions are their own event type); `wikipedia` = the season's schedule page, used only where the official calendar could not state the level for that season (Eastbourne 2023–2025); `resolver` = resolved after the seed dataset, by the same rules, from the event's name, tour and dates in that season. Null exactly when `tier` is null." }, "surface": { "type": [ "string", "null" ], "enum": [ "hard", "clay", "grass", null ], "description": "Court surface. Null where no source states one, never inferred from a tournament's usual surface in other seasons. TEAM COMPETITIONS (Davis Cup, Billie Jean King Cup, Laver Cup) have no surface at tournament level — each tie is played on the surface its host nation chose — so the match carries its TIE's surface, taken from the ITF's published tie record (venue, indoor/outdoor, surface) and the same for every rubber of that tie; `tournament.surface` stays null for them. A team-event match is null only when the tie's venue is not yet published or the match cannot be matched to a single tie (competition, date window and the nations on court must agree). The other structural null is UTR events, which are not in the vendor tournament catalogue at all and so carry `tournament_id: null` too. For every other event a surface that IS known is published on both the match and its `tournament`, and the two agree." }, "indoor": { "type": "boolean" }, "format": { "type": [ "string", "null" ], "enum": [ "BO3", "BO5", null ] }, "round": { "type": [ "string", "null" ], "description": "The feed's own free-text round label, verbatim. It is the round WITHIN the draw this match belongs to, and the draw is named by `is_qualifying` — NOT by this string. A qualifying draw has its own semi-final and its own final, so `\"Buenos Aires 3 - Semi-finals\"` with `is_qualifying: true` is the semi-final of the QUALIFYING draw, not of the tournament. Read the two fields together or not at all. The label also embeds the tournament name for most feeds — parse the suffix after the last `\" - \"`, or better, use `round_code`." }, "round_code": { "type": [ "string", "null" ], "enum": [ "F", "SF", "QF", "R16", "R32", "R64", "R128", "RR", "BR", "Q", "Q1", "Q2", "Q3", "Q4", "ER", null ], "description": "The round in the archive's controlled vocabulary, normalized from the free-text label above (`Q` = qualifying round the feed does not number). It matches `/history/archive/matches?round=` exactly. Null when the label is unrecognised — never guessed.\nIT IS DRAW-RELATIVE AND CANNOT, BY ITSELF, TELL YOU WHETHER A MATCH IS QUALIFYING. A qualifying semi-final carries `SF`, the same as a main-draw semi-final; only `Q`/`Q1`..`Q4` appear when the feed itself names the round as qualifying, which most feeds do not. To branch on main draw vs qualifying, use `round_code` AND `is_qualifying` together." }, "is_qualifying": { "type": [ "boolean", "null" ], "description": "Whether this match belongs to the QUALIFYING draw, as the source states it — never GUESSED from main-draw round vocabulary or from the tournament name. (A round the feed itself spells `Qualification Round 1` is the source stating it, and reads `true`: a `false` beside such a round is a payload contradicting itself, not a main-draw assertion. `Semi-finals` and `Final` are main-draw vocabulary and are never read that way.) This is the only field that separates a qualifying draw from the main draw, and it is load-bearing because the two are routinely carried under ONE tournament name with ONE round vocabulary: a tournament will publish a dozen `Semi-finals` and several `Final` that are all qualifying, a week before the main draw begins. Neither `tournament`, `tournament_id` nor `round_code` can tell them apart.\nTHREE-VALUED, and `null` is NOT `false`. `true`/`false` are the source's own assertion; `null` means no source has ever stated it — every row written before the field existed, and rows whose only feed carries no equivalent field. Treat `null` as unknown and filter accordingly, exactly as with every other nullable field on this object." }, "status": { "type": "string", "enum": [ "upcoming", "live", "completed", "cancelled" ], "description": "The settled lifecycle. `completed` is asserted only for a match we observed being played or whose match-winner market settled decisively (one side paid out) — a closed market alone never finishes a match (rule stated 2026-08-23; rows mis-published before it were corrected). `cancelled` with `event_status: null` means we hold positive evidence the match was not played as scheduled (the market settled void) but no vendor word for why — `outcome` and the fixture `reason` stay null rather than guessed, and the row upgrades to a completed walkover with `winner` / `withdrew` if a `Walk Over` with a stated winner lands later. The flip `upcoming → cancelled` runs through a gate (well past the scheduled time, no play recorded), never inline on a feed flap." }, "event_status": { "type": [ "string", "null" ], "enum": [ "Finished", "Retired", "Cancelled", "Walk Over", "Postponed", "Interrupted", "Unresolved", null ], "description": "The feed's own designator for the match state, passed through verbatim. `Finished` is by far the most common value — 144,266 of the 150,678 rows carrying one at 2026-09-18 — and until this version it was missing from this enum, so a strictly-validating generated client rejected the majority of completed matches. It is listed now, with `Unresolved` (every source lost the match before a result; see `outcome`). The rest name a match that did not run its course: retirement, cancellation, walkover, postponement, or an in-play suspension (`Interrupted` — rain/darkness/medical; the match is paused, not over). NULL does NOT mean \"completed normally\": it means the feed never stated anything for this match, which covers matches that ran their course and matches nothing was ever said about alike. `event_status: Finished` while `status` is still `live` is not a contradiction — one source has called the match over and we have not yet confirmed the final, so the score may stand still until we do (`stale` goes true, `age_seconds` climbs). Measured over the seven days to 2026-09-18, across 649 matches, that gap closed in 111 s at the median and 911 s at the ninetieth percentile; 85 ran past ten minutes. Two honest caveats: the value is cleared if a suspended match resumes (no record of the pause survives), and for `Retired`/`Walk Over` the withdrawing player is reported in `withdrew`, where derivable." }, "event_status_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When `event_status` last CHANGED, UTC (ISO-8601, `Z`) — added 2026-08-19. The instant WE recorded the walkover / retirement / cancellation / postponement / suspension (or its clearing), not when the tournament desk or the feed did: this is the field to measure our admin-status latency with. Bumps only on a change of value (a re-read of the same status never moves it; a clear back to null does). Null while `event_status` has never changed since the field was introduced (2026-08-19) — never backfilled, never guessed." }, "is_doubles": { "type": "boolean", "description": "Doubles match — kept for compatibility, and LOSSY. Evidence order: a doubles-team participant proves true regardless of the event type; otherwise the feed's event type decides. The loss: false also covers \"unknown\" — a match with no stated event type and no team participant reads false here, which is not a claim of singles. Prefer `draw`, whose null says so honestly." }, "draw": { "type": [ "string", "null" ], "enum": [ "singles", "doubles", null ], "description": "The honest THREE-VALUED draw (added 2026-08-18) — same vocabulary as the `?draw=` filter, decided by the same shared definition, so filter and field cannot disagree. Evidence order as is_doubles: a doubles-team participant proves doubles over any event type; otherwise the feed's event type decides. Null means neither says anything — the feed stated no event type, or the match is part of a team tie (Davis Cup / BJK Cup / United Cup class), where one event type covers both singles and doubles rubbers and we will not guess which this is. Null is NOT singles." }, "scheduled_time": { "type": [ "string", "null" ], "format": "date-time" }, "live_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The instant our feed last reported the match in play (UTC), added 2026-09-09 — the closest thing to an actual start time; a match that starts late has this well after `scheduled_time`, one that starts early has it before. Null for matches that went live before 2026-09-05 (when the stamp began) or were never observed live; re-stamped if a match is demoted and promoted again." }, "result_restated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the published result of this match was LAST corrected (UTC), added 2026-09-22 — the instant of the newest `restatement` row on `GET /matches/{matchId}/status-history`. A correction is any change to `status`, `event_status`, `winner` or the final score (sets, games) after the match was first published as completed (or as a cancelled walkover with a winner). Null when the result stands as first published. Present on every match surface. Poll `GET /history/matches?restated_since=` to find corrections." }, "result_version": { "type": "integer", "description": "`1` plus the number of corrections to the published result (added 2026-09-22). `1` = the result stands as first published; each `restatement` row on the status history adds one. Record it with the result you settle on and compare on re-read — a higher number means the result you hold was superseded, and the status history says what changed." }, "players": { "type": "object", "properties": { "p1": { "$ref": "#/components/schemas/Player" }, "p2": { "$ref": "#/components/schemas/Player" } } }, "score": { "oneOf": [ { "$ref": "#/components/schemas/Score" }, { "type": "null" } ] }, "winner": { "type": [ "integer", "null" ], "description": "Completed matches only — derived from final sets. Served for the full archive age: a match older than the live-table window reads its final state from the same store the tape serves, so old completed matches carry a winner too." }, "outcome": { "type": [ "string", "null" ], "enum": [ "completed", "retired", "walkover", "default", "abandoned", "unresolved", null ], "description": "The settlement outcome (added 2026-08-18), one closed vocabulary derived from `status` + `event_status` so the two can never disagree: `completed` = ran its full course; `retired` = a player retired in play; `walkover` = conceded before a ball was struck; `default` = a player was defaulted; `abandoned` = called off unfinished with no result awarded; `unresolved` (added 2026-09-10) = every source lost the match before a result and it was closed unfinished — `score` is the last state we observed, `winner` is null and no result is asserted; it flips to `completed` with the proven final when an authority confirms the result. NULL while the match is upcoming/live and on a cancelled fixture that never produced a result — null is not `completed`. Branch settlement on this field, never on `event_status` spellings. New values may be added within v1; handle unknowns gracefully." }, "withdrew": { "type": [ "integer", "null" ], "description": "Completed matches only — which player retired or conceded the walkover (1|2). Present only when `event_status` is `Retired`/`Walk Over` and the winner is derivable; the withdrawer is the loser by the rules of the sport. Absent means \"not a withdrawal, or no evidence\" — never a guess." }, "has_analysis": { "type": "boolean", "description": "Whether a model thesis or profile exists for this match — on every list row and the detail, every tier (since 2026-09-02). Filter the slate on this before calling `/matches/{matchId}/analysis`, which answers `404 no_analysis` about the same fact." }, "has_market": { "type": "boolean", "description": "Whether a match-winner market is mapped to this match (every tier, since 2026-09-02). Same role for `/markets/{matchId}/prices` (`404 no_market`)." } } }, "MatchDetail": { "allOf": [ { "$ref": "#/components/schemas/Match" }, { "type": "object", "properties": { "analysis": { "$ref": "#/components/schemas/Analysis", "description": "ULTRA only (absent below)" }, "market": { "oneOf": [ { "$ref": "#/components/schemas/Market" }, { "type": "null" } ], "description": "PRO+ only (absent below)" } } } ] }, "Analysis": { "type": "object", "properties": { "thesis": { "type": [ "object", "null" ], "properties": { "pick_side": { "type": "integer", "enum": [ 1, 2 ] }, "confidence": { "type": [ "number", "null" ] }, "win_probability_pick": { "type": [ "number", "null" ] }, "state": { "type": [ "string", "null" ], "enum": [ "valid", "confirmed", "weakened", "broken", null ] }, "reasoning": { "type": [ "string", "null" ] }, "notes": { "type": "object", "properties": { "matchup": { "type": [ "string", "null" ] }, "environment": { "type": [ "string", "null" ] }, "fatigue": { "type": [ "string", "null" ] } } }, "scenario_playbook": { "type": [ "array", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "profile": { "type": [ "object", "null" ], "properties": { "win_probability_p1": { "type": [ "number", "null" ] }, "expected_closeness": { "type": [ "number", "null" ] }, "volatility_rating": { "type": [ "string", "null" ], "enum": [ "low", "med", "high", null ] }, "stage": { "type": [ "string", "null" ], "enum": [ "pregame", "live", null ], "description": "Did this forecast already see the match? null = UNKNOWN, never pregame." }, "model_version": { "type": [ "string", "null" ], "description": "The prompt-scaffold version this forecast was produced under, so a forecast can be evaluated against the framing that produced it and a scaffold change reads as a regime break rather than unexplained drift. Null on profiles written before the stamp existed." }, "input_state": { "type": [ "object", "null" ], "description": "For an in-play forecast (stage=live), the score it was actually looking at, so it can be evaluated against the position rather than only excluded. Null on a pregame profile (it saw no score) and null wherever the state could not be established. NOT reconstructed from the score at created_at — that timestamp is written after the model finishes, so it lands later than what the model saw.", "properties": { "capture": { "type": "string", "enum": [ "writer", "recovered" ], "description": "writer = stamped as the forecast was produced, from the score row itself (carries live_score_id and stats). recovered = reconstructed from the stored prompt text of that same forecast; the score is exact but there is no live_score_id and no stats." }, "live_score_id": { "type": [ "integer", "null" ] }, "total_games": { "type": [ "integer", "null" ] }, "score": { "type": [ "object", "null" ], "description": "server is the serving SIDE (1 or 2); on doubles that is the team, not the individual.", "properties": { "sets": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "games": { "type": [ "array", "null" ] }, "points": { "type": [ "array", "null" ] }, "server": { "type": [ "integer", "null" ] }, "is_tiebreak": { "type": [ "boolean", "null" ] }, "timestamp": { "type": [ "string", "null" ], "format": "date-time" } } }, "stats": { "type": [ "object", "null" ] } } }, "key_factors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "Market": { "type": "object", "properties": { "id": { "type": "integer" }, "question": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "active", "resolved", "closed", null ] }, "volume": { "type": [ "number", "null" ] }, "liquidity": { "type": [ "number", "null" ] }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "prices": { "type": "array", "description": "Prices endpoint / match detail only; newest first", "items": { "$ref": "#/components/schemas/Price" } } } }, "Price": { "type": "object", "description": "Prediction-market top-of-book quote (probability-like, [0,1]); reflects market trading, not an official line, and can lag live scores. Tagged so a synthesised quote is never mistaken for a live book.", "properties": { "side": { "type": [ "integer", "null" ], "description": "1 = players.p1's outcome, 2 = players.p2's - decided by our name-verified match-market mapping, never by the venue's own display order (the venue lists roughly half of all pairings the other way round). Fixed 2026-09-09: ticks served before that date followed the venue's display order, so on those markets side was reversed; the mapping is stored, so re-reading any tick now returns the correct side." }, "bid": { "type": [ "number", "null" ] }, "ask": { "type": [ "number", "null" ] }, "mid": { "type": [ "number", "null" ], "description": "The venue's observed midpoint at the instant we polled or streamed it - never a model estimate. Only mid is always real; see synthetic." }, "spread": { "type": [ "number", "null" ] }, "price_source": { "type": [ "string", "null" ], "description": "Feed category, e.g. prediction_market" }, "synthetic": { "type": [ "boolean", "null" ], "description": "true = bid/ask are estimated from mid (mid +/- 0.005, not a live order book) - mid itself is the venue's observed midpoint, never a model estimate; false = real top-of-book from the live order-book stream; null = unknown (older ticks). The live stream attaches when a match goes live, so pre-match ticks are synthetic: true by design." }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "When we observed this quote (UTC) - our observation clock, not a venue publication time." } } }, "PointPrice": { "type": "object", "description": "One played point with the match-winner quote in force per side when it was captured (added 2026-09-15). The score state is the BASIC tape's; the ULTRA-only per-point fields (server, winner, serve, outcome) are not here. Prices are keyed by neutral side and carry no venue or token identifiers.", "properties": { "seq": { "type": "integer", "description": "Per-match monotonic position 1..N — the same seq as the live points row." }, "at": { "type": "string", "format": "date-time", "description": "Our capture time of the point (UTC)." }, "sets": { "type": "array", "items": { "type": "integer" } }, "games": { "type": "array", "description": "Per-set games arrays, [p1, p2].", "items": { "type": "array", "items": { "type": "integer" } } }, "score": { "type": "object", "properties": { "p1": { "type": [ "string", "null" ] }, "p2": { "type": [ "string", "null" ] } } }, "tiebreak": { "type": "boolean" }, "prices": { "type": "object", "description": "Keyed by side — \"1\" = players.p1's outcome, \"2\" = players.p2's.", "properties": { "1": { "type": [ "object", "null" ], "description": "The quote for this side, or null when no usable quote exists for the point.", "properties": { "bid": { "type": [ "number", "null" ] }, "ask": { "type": [ "number", "null" ] }, "mid": { "type": [ "number", "null" ] }, "spread": { "type": [ "number", "null" ] } } }, "2": { "type": [ "object", "null" ], "description": "The quote for this side, or null when no usable quote exists for the point.", "properties": { "bid": { "type": [ "number", "null" ] }, "ask": { "type": [ "number", "null" ] }, "mid": { "type": [ "number", "null" ] }, "spread": { "type": [ "number", "null" ] } } } } }, "lag_seconds": { "type": [ "integer", "null" ], "description": "Seconds between the quote and the point, the larger of the two sides (a negative side lag means the first quote after the point was used); null when no side aligned." }, "resolution": { "type": [ "string", "null" ], "enum": [ "tick", "minute", "coarse", null ], "description": "tick |lag| <= 15 s, minute <= 90 s, coarse beyond — the coarser of the two sides; null when no side aligned. An honest label, never upgraded." } } }, "SlateEvent": { "description": "An Event as served by the slate-wide feed (GET /events) — the per-match row plus its id and match.", "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "id": { "type": "integer", "description": "The event's id; the `after_id` cursor." }, "match_id": { "type": "integer" } } } ] }, "Event": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "break", "set_won", "game_won", "momentum_run", "stoppage_start", "stoppage_end", "pause_start", "pause_end", "medical_timeout_start", "medical_timeout_end", "trainer_called", "trainer_called_end", "toilet_break_start", "toilet_break_end" ], "description": "The stoppage family (added 2026-09-12). `medical_timeout_start/end`, `trainer_called/_end` and `toilet_break_start/end` are stated by the match scorer or chair umpire, with `player` = the player concerned. Coverage (2026-09-13): WTA, WTA 125, Challenger and UTR singles — WTA and WTA 125 from the umpire console in two layers: the match state within ~20 s (`trainer_called`, `toilet_break_*`, `stoppage_*`, player null) and the console's event feed, published by the tour with a variable delay (measured 2026-09-13: about one minute to an hour behind play), which adds `medical_timeout_start/end` with the player and exact instants; Challenger and UTR from the scorer timeline (22 of 70 finished Challenger matches, median 8 s). ITF World Tennis Tour singles from the court's live-scoring state (the state, not the player: `player` is null on ITF rows; first medical timeout observed and published 2026-09-13). ATP main tour: a public live-score service's match stage is watched for its medical-timeout and interruption stages — present in its vocabulary, not yet observed on a tennis match, so ATP rows are mapped, not yet proven (`player` null, `at` = our observation instant). Not doubles. `stoppage_start/end` is a whole-match stop (`reason` weather | other when stated, unknown when only a bare suspension flag reached us). `pause_start/end` is an interruption of play measured from our own point clocks (`basis: inferred`), never labelled medical." }, "player": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "Stoppage family — the UTC instant the stoppage happened (for a pause, its last score change)." }, "detected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Stoppage family — when we recorded it." }, "basis": { "type": [ "string", "null" ], "enum": [ "observed", "inferred", null ], "description": "Stoppage family — observed (a source stated it) or inferred (measured from our clocks)." }, "reason": { "type": [ "string", "null" ], "description": "Stoppage family — medical_timeout | unspecified | no_treatment | taping | changeover_treatment | evaluating | failed | toilet_break | weather | other | resumed | unknown." }, "position": { "type": [ "string", "null" ], "enum": [ "point", "changeover", "setbreak", null ], "description": "pause rows only — where the last point left the match, which sets the silence threshold." }, "score": { "type": [ "object", "null" ], "description": "Stoppage family — sets, games, points, server at the moment of the stoppage." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "end rows only." } } }, "BroadcastObject": { "type": "object", "description": "One flat object for a live-graphics template. EVERY key below is present on every read; a value we do not hold is `null` rather than absent, because a missing key breaks a template binding. Points and the set line are already in display form.", "properties": { "match_id": { "type": "integer" }, "status": { "type": "string", "description": "`live`, `completed`, `upcoming`" }, "event_status": { "type": [ "string", "null" ], "description": "The terminal badge where one is stated (`Finished`, `Retired`, `Walk Over`, `Interrupted`); null on a normal live row." }, "outcome": { "type": [ "string", "null" ] }, "winner": { "type": [ "integer", "null" ], "description": "1 or 2, null until a result is established." }, "tour": { "type": [ "string", "null" ] }, "tournament": { "type": [ "string", "null" ] }, "round": { "type": [ "string", "null" ] }, "surface": { "type": [ "string", "null" ] }, "best_of": { "type": [ "integer", "null" ] }, "is_doubles": { "type": "boolean" }, "p1_id": { "type": [ "integer", "null" ] }, "p1_name": { "type": [ "string", "null" ] }, "p1_short": { "type": [ "string", "null" ], "description": "Display short form, `\"J. Sinner\"`. A doubles team keeps each side's last token." }, "p1_country": { "type": [ "string", "null" ], "description": "Three-letter code." }, "p1_ranking": { "type": [ "integer", "null" ] }, "p2_id": { "type": [ "integer", "null" ] }, "p2_name": { "type": [ "string", "null" ] }, "p2_short": { "type": [ "string", "null" ] }, "p2_country": { "type": [ "string", "null" ] }, "p2_ranking": { "type": [ "integer", "null" ] }, "p1_sets": { "type": [ "integer", "null" ] }, "p2_sets": { "type": [ "integer", "null" ] }, "p1_games": { "type": [ "integer", "null" ], "description": "Games in the set in play." }, "p2_games": { "type": [ "integer", "null" ] }, "p1_points": { "type": [ "string", "null" ], "description": "As printed: `\"0\"`, `\"15\"`, `\"30\"`, `\"40\"`, `\"AD\"`, or the tiebreak count." }, "p2_points": { "type": [ "string", "null" ] }, "p1_set1": { "type": [ "integer", "null" ], "description": "Per-set columns. A set not yet played is null on both sides." }, "p2_set1": { "type": [ "integer", "null" ] }, "p1_set2": { "type": [ "integer", "null" ] }, "p2_set2": { "type": [ "integer", "null" ] }, "p1_set3": { "type": [ "integer", "null" ] }, "p2_set3": { "type": [ "integer", "null" ] }, "p1_set4": { "type": [ "integer", "null" ] }, "p2_set4": { "type": [ "integer", "null" ] }, "p1_set5": { "type": [ "integer", "null" ] }, "p2_set5": { "type": [ "integer", "null" ] }, "set_line": { "type": [ "string", "null" ], "description": "The completed and in-play sets as one string, `\"5-7 2-0\"`." }, "current_set": { "type": [ "integer", "null" ] }, "is_tiebreak": { "type": "boolean" }, "match_tiebreak": { "type": "boolean", "description": "True while a deciding match tiebreak is in play." }, "server": { "type": [ "integer", "null" ], "description": "1 or 2." }, "p1_serving": { "type": [ "boolean", "null" ] }, "p2_serving": { "type": [ "boolean", "null" ] }, "break_point_for": { "type": [ "integer", "null" ], "description": "1, 2 or null. Cue an animation on the transition to non-null." }, "set_point_for": { "type": [ "integer", "null" ] }, "match_point_for": { "type": [ "integer", "null" ] }, "p1_win_pct": { "type": [ "integer", "null" ], "description": "The model probability as a whole percent. Null where no model figure was computed for this state — never guessed." }, "p2_win_pct": { "type": [ "integer", "null" ] }, "sequence": { "type": [ "integer", "null" ], "description": "The per-match accept counter. THIS is how a poller detects a new state." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "age_seconds": { "type": [ "integer", "null" ], "description": "Seconds since the score CONTENT last changed." }, "stale": { "type": [ "boolean", "null" ], "description": "A live match whose content has frozen past the threshold." }, "served_at": { "type": "string", "format": "date-time", "description": "When this response was built. Changes on every read — do not use it to detect a new state." } } }, "ScoreWithdrawal": { "type": "object", "description": "One withdrawn score state on a match (added 2026-09-25), from the durable record behind `GET /matches/{matchId}/withdrawals`.", "properties": { "sequence": { "type": "integer", "description": "The refused state's `sequence` — the value you hold from the feed, and the frame's `superseded_sequence`." }, "kind": { "type": "string", "enum": [ "withdrawn", "deferred", "withheld" ], "description": "The frame's `kind`. Only `withdrawn` means discard and resume." }, "reason": { "type": "string", "description": "The legality gate's slug, the same value the frame carries." }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the refused state's OWN `score` frame was handed to the push feed. Null when that state never went out on the feed — the judgement was still made and the REST read served it." }, "withdrawn_at": { "type": "string", "format": "date-time", "description": "When the judgement was made. The frame's `ts`." }, "replaced_by_sequence": { "type": [ "integer", "null" ], "description": "The `sequence` of the state served in the refused one's place, the newest legal state at that moment. Null on `withheld`, where nothing within the scan was publishable. It is on the record and NOT on the frame." }, "frame": { "type": "object", "description": "The `score_withdrawn` frame exactly as the push feed, the native WebSocket and webhooks sent it, stamped once so the stored copy is the wire copy. Its keys are `type`, `match_id`, `kind`, `superseded_sequence`, `reason`, `safe_to_resume`, `ts` and `published_at`. It carries NO replacement score and no new sequence: the state to resume from is the one on the next `score` frame, or on a fresh `GET /matches/{matchId}/score`." } } }, "StatusChange": { "type": "object", "description": "One row of the per-match status ledger (added 2026-09-12).", "properties": { "at": { "type": "string", "format": "date-time", "description": "The instant we published the change (UTC)." }, "status": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] } } }, "event_status": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] } } }, "outcome": { "type": [ "string", "null" ], "description": "Derived from the after-state by the Match.outcome definition." }, "basis": { "type": "string", "enum": [ "observed", "backfill", "restatement" ], "description": "How the row was made. observed = written at the instant of the change (from 2026-09-11T22:45:48Z); backfill = reconstructed on 2026-09-12 from the one stamp per kind the match row kept before the ledger existed (last promotion to live from 2026-09-05, completion instant from 2026-08-21, last reopen, last event_status change). One row per stamp; overwritten intermediate transitions are not recovered. restatement (added 2026-09-22) = a CORRECTION to a result that had already been published — the match's `status`, `event_status`, winner or final score (sets, games) changed after it was first published as completed (or as a cancelled walkover with a winner). A correction is always a new row, never an edit, written at the instant we made the change; `status` / `event_status` carry before and after as usual (the same value twice when only the winner or the score moved) and its `score` is the result AFTER the correction (null when the match holds no score row, as on a walkover). Every path that can change a result writes one — a source's late final, a second authority's correction, an operator's repair, a completion reopened and re-closed — because it is enforced where the result is written. A re-assertion of the same result, or a change to points alone, is not a correction and writes nothing. `result_restated_at` and `result_version` on the Match summarise these rows. Rows with this basis exist from 2026-09-22; earlier corrections were not signalled." }, "score": { "type": [ "object", "null" ], "description": "The newest score row at that instant (sets, games, points, server); null when none existed." } } }, "Fixture": { "type": "object", "properties": { "id": { "type": "integer" }, "event_date": { "type": [ "string", "null" ], "format": "date" }, "start_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Scheduled start (UTC). Null until the order of play assigns a time — a date-only fixture is a real state, and rows written before 2026-08-03 stay null." }, "player1_id": { "type": [ "integer", "null" ], "description": "Our player id, when the participant is in our roster (exact-key resolution, never a name match). Null otherwise — names are always present regardless." }, "player2_id": { "type": [ "integer", "null" ], "description": "As `player1_id`, for the second participant." }, "tour": { "type": [ "string", "null" ], "description": "The record's OWN tour, which is NOT the `tour` filter vocabulary. It is granular (`juniors_boys`, `juniors_girls`, `challenger_men`) where the filter is grouped (`juniors`, `challenger`), and a doubles team reports it UPPERCASE (`ATP`) where an individual reports lowercase (`atp`). Treat it as an opaque string; do not parse it into the filter enum." }, "tournament": { "type": [ "string", "null" ] }, "round": { "type": [ "string", "null" ] }, "round_code": { "type": [ "string", "null" ], "enum": [ "F", "SF", "QF", "R16", "R32", "R64", "R128", "RR", "BR", "Q", "Q1", "Q2", "Q3", "Q4", "ER", null ], "description": "Normalized round — same vocabulary as `Match.round_code`. Null when the label is unrecognised, never guessed." }, "surface": { "type": [ "string", "null" ] }, "player1_name": { "type": [ "string", "null" ] }, "player2_name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "ModelProfile": { "type": "object", "description": "One model win-probability profile. On the history tape these are the profiles produced during the match, oldest first.", "properties": { "win_probability_p1": { "type": [ "number", "null" ] }, "expected_closeness": { "type": [ "number", "null" ] }, "volatility_rating": { "type": [ "string", "null" ], "enum": [ "low", "med", "high", null ] }, "stage": { "type": [ "string", "null" ], "enum": [ "pregame", "live", null ], "description": "Did this forecast already see the match? null = UNKNOWN, never pregame." }, "model_version": { "type": [ "string", "null" ], "description": "The prompt-scaffold version this forecast was produced under. Null on profiles written before the stamp existed." }, "key_factors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "HistoryTapeRow": { "type": "object", "description": "One row of the score sequence. Rows we watched live carry a real `timestamp`. Rows expanded after the fact from a finished-match point-by-point record carry a null `timestamp` AND null model fields, because neither a wall clock nor a model output ever existed for them — nothing is synthesised. `origin` (since 2026-09-20) says explicitly which kind each row is, read from the row's stored provenance — never inferred from its clock; a null `timestamp` remains true of every reconstructed row. The model fields alone are not a marker, since they are stamped best-effort and an observed row may lack them. `meta.point_source` / `meta.coverage` say which kind of tape you are holding. `origin`, `serve` and `outcome` are present on `GET /history/matches/{matchId}` rows; the pre-2023 ArchiveTape (every row reconstructed) does not carry them. `winner` (since 2026-09-22) is present on EVERY row of every sequence, on both — who won the point that produced the row, judged from the score step and from nothing else; `server`, `serve` and `winner` together are the three per-point facts a model needs, and the third was only implicit in the score step before. Reconstructed rows are never repaired or reordered: a game whose vendor point record is internally inconsistent is withheld whole, not fitted or patched into a legal sequence — see `meta.points.games_withheld` (added 2026-09-20).", "properties": { "origin": { "type": "string", "enum": [ "observed", "reconstructed" ], "description": "`observed` — a row our own pipeline committed while the point was being played; `reconstructed` — a row expanded after the fact from a finished-match point-by-point record (null timestamp, null model fields). From the stored provenance, never inferred from a null timestamp. Added 2026-09-20." }, "serve": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "The serve the point was played on (1 first, 2 second), joined from this match's per-point stream: paired by EXACT score state — set count, every set's games, in-game points and tiebreak flag all equal — and, where a state recurs (a deuce cycle), by nearest clock within 90 seconds (the tape row's observed clock against the stream point's), each stream point used at most once; otherwise null. Observed rows only: null on every reconstructed row, on a row no stream point matches, and on a recurring state with no clock within the window or two at the same distance. Never inferred from the score or the pattern of play. Added 2026-09-20; clock pairing 2026-09-21." }, "outcome": { "type": [ "string", "null" ], "enum": [ "ace", "double_fault", "winner", "forced_error", "unforced_error", null ], "description": "How the point ended, as an outside source states it — same join rule and same nulls as `serve`. `meta.enrichment` says what landed on this tape. Added 2026-09-20." }, "sets": { "type": "array", "items": { "type": "integer" } }, "games": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } }, "points": { "type": "array", "description": "In-game points as tennis strings (\"0\", \"15\", \"30\", \"40\", \"AD\") — EXCEPT during a tiebreak, where they are the running tiebreak count as plain integer strings (\"0\", \"1\", \"2\", …); `is_tiebreak` tells the two notations apart.", "items": { "type": "string" } }, "server": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "Who is serving — null where the feed never asserted it. On `?sequence=clean` the server is SETTLED per non-tiebreak game (the server is physically constant within a game, so the game's majority assertion fills nulls and corrects transient disagreements; a tie settles nothing). The raw sequence carries every row exactly as committed, so a transient wrong-server read can appear there and be corrected by a later row. TIEBREAK ROWS ARE NEVER SETTLED, on either sequence: the server genuinely changes during a breaker, so there is no constant to take a majority of, and the field is the source's own assertion carried through. Two consequences, both reported by a Basic customer on 2026-09-25 and confirmed in the code. The rotation cannot be reconstructed from the rows served wherever the tape is sampled — a breaker whose rows skip points gives you the server of a state, not of a numbered point, and `meta.points.transitions_legal` against `transitions_total` tells you whether that happened. And on the set roll-up row that carries `tiebreak_final`, `server` is the value of that committed set-end state: it is NOT a preserved copy of the final breaker point's server, and we make no claim that it is. Withhold server-dependent tiebreak analysis unless the encoding reconciles on the match in front of you." }, "is_tiebreak": { "type": "boolean" }, "tiebreak_final": { "type": [ "array", "null" ], "description": "Added 2026-09-24. The breaker's closing score in our player order, e.g. `[2, 7]`, on the row that CLOSES a tiebreak set. Absent on every other row, including the breaker rows themselves, which stay exactly as they were observed. Same value, from the same resolver, as this set's entry in the response's `tiebreaks` array, so the two never disagree. The row that closes a set carries the decided games before the set counter catches up, and since 2026-09-24 the games on the row decide it, so the field does not depend on which row the counter moves on. Before that a set whose counter lagged by a row was never stamped and stayed empty on every later read, while `tiebreaks` stated the final.", "items": { "type": "integer" }, "example": [ 2, 7 ] }, "win_probability_p1": { "type": [ "number", "null" ], "description": "The model read stamped on this row while the match was live. The tape carries NO model-regime stamp — there is no `model_version` or `generated_at` column here, nor in the bulk `tape` packages — so segregate a recorded tape corpus by this row's `timestamp` against the two regime boundaries documented on `Score.win_probability_meta`: 2026-08-18T08:29:28Z and 2026-09-16T07:59:54Z." }, "danger": { "type": [ "number", "null" ] }, "timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "On tape rows since 2026-09-24. The instant our arbiter accepted this state (UTC), stamped once at insert and never refreshed by a re-assertion. This is the clock to difference a timing study against: `timestamp` starts equal to it and is then refreshed while the owning source keeps re-asserting the unchanged state, so on most raw rows `timestamp` is a later re-assertion instant (measured on match 189679: 164 of its 171 observed rows carry a `timestamp` more than a second after `accepted_at`). Null on every reconstructed row, which never had a clock. IT ALSO HAS A START DATE ON THE ARCHIVED TAPE, and this description claimed the opposite (\"it rides the whole observed corpus\") until 2026-10-01. THAT DATE MOVED BACK SIX WEEKS ON 2026-10-01. A tape answered from the archive (`meta.from_archive: true`) now carries the clock on every observed row from 2026-08-11: 100.0% of every day from 2026-08-11 to 2026-10-01, 92.5% of 2026-08-10 (the live column's own first instant is `2026-08-10T08:07:42Z`), and 0.0% of every day before that. Over the whole archived observed corpus, 1,721,102 of 4,663,181 rows carry it (36.9%, against 307,631 before the backfill): 0.0% of every month to July 2026, 68.8% of August, 100.0% of September and of October. The boundary was 2026-09-23, the day the archive column landed, until a backfill took each missing value from the live row that archived row had been copied from: 1,413,471 clocks and 1,393,458 counters, inside 1,538,176 rows over 14,491 matches. Nothing is derived, rounded or taken from a neighbouring row, and a row whose live row was already trimmed at the 90-day retention stays null for good. Wire-verified on match 2168 (26 April 2026), before the boundary: 131 observed rows, `timestamp` on all 131 and `accepted_at` on none. Match 189679's own archived copy carried the clock on 0 of its 171 observed rows before that run and on 171 of 171 after it, which is why the 189679 measurement above holds either way: that match is served with `from_archive: false`. So read `meta.from_archive` before planning a timing study, and treat a null here as a boundary of the record rather than as a missing value." }, "received_at": { "type": [ "string", "null" ], "format": "date-time", "description": "On tape rows since 2026-09-24. The instant this state reached our edge, before the arbiter ran, stamped once. `accepted_at` minus `received_at` is our own arbitration step; neither figure is a claim about how fast anything upstream is, and neither is the court's clock. `timestamp` is the only one of the three with no start date: this clock begins 2026-09-24 and `accepted_at` begins 2026-08-11 on an archived tape (this description said the other two had no start date until 2026-10-01, which was wrong about `accepted_at` — see `HistoryTapeRow.accepted_at`). This is also the one clock the 2026-10-01 archive backfill could not move: the live column landed 2026-09-24, a day AFTER the archive column, so every live row carrying an arrival clock was archived with it and the recoverable count is zero. It is stamped only as a state arrives, so it can never be filled in afterwards: the earliest one we hold is `2026-09-24T02:00:26Z`, and on every observed row accepted before that instant it is null while `timestamp` is populated. Measured on match 189679 (12 September) after a Basic customer reported it on 2026-09-25: 171 observed rows, `accepted_at` on all 171, `received_at` on none — a match served from its live rows, so it says nothing about the archived tape. Null on every reconstructed row." }, "sequence": { "type": [ "integer", "null" ], "description": "On tape rows since 2026-09-26. This state's per-match ACCEPT COUNTER — the same number `GET /matches/{matchId}/withdrawals` publishes as `sequence` and `replaced_by_sequence`, and the same counter as `Score.sequence` on a live read. It is what makes the withdrawal ledger's pointer resolvable: told \"sequence 104 was withdrawn, resume from 103\", you can now find 103 on the tape, and because a withdrawn state never enters the record at all the withdrawal shows up here as a GAP in the run of counters. Before this the tape published no such number, so the pointer named a row nothing identified — reported by an Ultra customer who wrote that \"the history rows lack sequence IDs, so these responses alone cannot reconstruct exactly what a live client received\". NULL, NEVER FABRICATED, IN TWO CASES, and both are honest gaps rather than errors: a row whose archived copy could not be filled from its own live row, and the pre-2023 archive tape, which has no such counter because no live accept ever happened. The 2026-10-01 backfill moved the first of those from 2026-09-26 back to 2026-08-14, so the archived counter is on 68.2% of 2026-08-14, 99.3% of 08-15, 95.9% or more of every day from 2026-08-16 and 100% from 2026-09-01; before that the counter died with the live row at the 90-day retention. Unlike the two clocks it is NOT null on a reconstructed row: a counter is a fact about our own accept order, so wherever one is present a live reader really did receive that state at that position." }, "winner": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "Who won the point that produced this row — `1` | `2`, judged from the score step between this row and the previous served row (the previous raw row on the raw sequence, the previous clean row under `?sequence=clean`), by the same rule the completeness ledger counts a legal transition with — and from nothing else: never the serve, the server, the outcome tag or the pattern of play. Null on the first row and wherever the step is not one attributable point: a re-sent row (an identical state — null on raw, collapsed away on clean), a set opener (same games totals, the arrays extended by `[0,0]`), a backward correction, a multi-game jump. A step whose games total rises by exactly one attributes to the side whose count rose (the game point was theirs) whatever in-game points the step skipped — a missed poll, or a game the strict expander withheld whole; `meta.points.games_withheld` says when the latter happened. Present on every row of every sequence, observed and reconstructed, and on the pre-2023 ArchiveTape; equal to `point_winner` wherever that older key is present. Derived once per response, never stored. Added 2026-09-22." }, "point_winner": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "The same verdict as `winner` under the older key, kept unchanged for existing readers. Who won the point this row records — PRESENT ONLY on `?sequence=clean` and `?points=complete` rows, and only where the transition from the previous row of the served sequence is a single attributable point; null on gaps, torn rows and the first row. Never on the plain raw sequence (raw is deliberately non-monotonic: consecutive raw rows are corrections, not points — a `points=complete` read is the exception, because there the served order IS point order). Derived at read time, never stored or guessed. Since 2026-09-22 `winner` carries the same verdict on every row of every sequence." } } }, "HistoryTape": { "type": "object", "properties": { "match": { "$ref": "#/components/schemas/Match" }, "tape": { "type": "array", "description": "Chronological score sequence — see HistoryTapeRow", "items": { "$ref": "#/components/schemas/HistoryTapeRow" } }, "tiebreaks": { "type": [ "array", "null" ], "description": "Per-set tiebreak final scores, aligned to the sets of the final scoreline: {\"p1\", \"p2\"} for each 7-6 set, null per set otherwise; null when the match has no 7-6 set. Each entry comes from the tape's own terminal breaker state (max >= 7, margin >= 2 — always wins), a source's finished-match summary, or the point-by-point reconstruction — named per set in meta.tiebreaks_source. Nothing is inferred from a partial state: a breaker whose closing point no source states reads null rather than an under-report. Before 2026-09-16 only the tape kind existed and the array was null on ~99% of 7-6 sets. TIMING. Only the `tape` kind is available the instant a match ends. `summary` and `reconstruction` entries are written by a finals pass that runs ONCE A DAY, so a match that finished earlier the same day commonly reads null for its 7-6 sets and carries them from the next pass onward. Measured 2026-09-17: of 7-6 sets in matches completed on the five previous days, 72-100% were populated; of those completed the same day, 8%. Re-read a fresh match the following day before treating a null as final.", "items": { "type": [ "object", "null" ], "properties": { "p1": { "type": "integer" }, "p2": { "type": "integer" } } } }, "profiles": { "type": "array", "description": "Model profiles, oldest first (Analysis `profile` shape)", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "match_id": { "type": "integer" }, "rows": { "type": "integer", "description": "Rows RETURNED — after any `sequence=clean` collapse." }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "point_source": { "type": [ "string", "null" ], "enum": [ "observed", "reconstructed", "mixed", null ], "description": "Where the rows came from — `observed` (every row watched live), `reconstructed` (every row expanded after the fact), `mixed` (a reconstructed opening followed by what we watched), or null on an empty tape. Reported once here and never per row, so the row shape cannot carry data-source provenance." }, "raw_rows": { "type": "integer", "description": "Rows BEFORE any collapse — equals `rows` when `sequence=raw`." }, "unique_states": { "type": "integer", "description": "Distinct score states in the raw tape. `raw_rows` minus this is pure repetition." }, "sequence": { "type": "string", "enum": [ "raw", "clean" ], "description": "Echoes the requested `?sequence=`." }, "from_archive": { "type": "boolean", "description": "The rows were served from the immutable archive rather than the live table. Informational — the content contract is identical." }, "points": { "$ref": "#/components/schemas/PointsMeta" }, "tiebreaks_source": { "type": [ "array", "null" ], "description": "Aligned to the top-level `tiebreaks`: per set, where that set's breaker final came from — `tape` (the served tape reached a terminal breaker state), `summary` (a source's finished-match summary) or `reconstruction` (the point-by-point reconstruction) — or null where the entry is null. Null when `tiebreaks` is null. `summary` and `reconstruction` are written by the once-a-day finals pass (see `tiebreaks`), not at the moment a match ends.", "items": { "type": [ "string", "null" ], "enum": [ "tape", "summary", "reconstruction", null ] } }, "reconstructed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the newest RECONSTRUCTED row in this response was written (UTC) — when the reconstruction you are holding landed. Null when no reconstructed row is served. Measured on the rows returned, after any sequence=clean collapse. Added 2026-09-20." }, "observed_span": { "type": [ "object", "null" ], "description": "The `timestamp` of the first and last OBSERVED rows in this response, in served order. Null when no observed row is served. Added 2026-09-20.", "properties": { "first": { "type": [ "string", "null" ], "format": "date-time" }, "last": { "type": [ "string", "null" ], "format": "date-time" } } }, "enrichment": { "type": "object", "description": "What serve/outcome tags actually landed on the rows of THIS response — the per-point stream's vocabulary. `none`/`none` on a wholly reconstructed tape. Added 2026-09-20.", "properties": { "serve": { "type": "string", "enum": [ "stated", "none" ] }, "outcome": { "type": "string", "enum": [ "full", "ace_double_fault", "none" ] } } }, "generated_at": { "type": "string", "format": "date-time" } } } } }, "PointsMeta": { "type": "object", "description": "Measured point-completeness of the sequence ACTUALLY RETURNED, computed at read time — never a stored blanket claim, and only ever a per-match measurement. Always present on `?points=complete` responses (with `available_complete`); on default reads it appears where enabled. Orthogonal to `coverage`: coverage says how the rows were OBTAINED, this says how COMPLETE the sequence is.", "properties": { "complete": { "type": "boolean", "description": "The contract bit: a statement that the served sequence holds AT LEAST EVERY POINT THE SCORE REQUIRES — not merely that consecutive rows are consistent with each other. True only when the sequence opens at 0-0, EVERY transition is a legal single-point step, it carries at least as many point transitions as the final scoreline implies the match contained, EVERY completed game holds at least as many point transitions as that game must have contained (`games_short` is 0 — a whole game the tape skips is a legal 0-0 → 0-0 boundary the transition test alone cannot see, added 2026-09-21), it reaches a finished legal final scoreline at love (or the match ended early — retirement/walkover), it is not known-truncated, and no game was withheld (`games_withheld`)." }, "completeness": { "type": [ "number", "null" ], "description": "Legal single-point transitions over a LOWER-BOUND expected point count derived from the final scoreline. 1.0 for any complete tape, low for a sampled one. Descriptive only — the denominator is a floor, not the true point count — and null when the final scoreline is unreadable." }, "rows": { "type": "integer", "description": "Rows measured — always equals `meta.rows`." }, "transitions_legal": { "type": "integer", "description": "Transitions attributable to exactly one side winning one point." }, "transitions_total": { "type": "integer", "description": "All row-to-row transitions, excluding re-sent rows (rows − 1 − `resent_rows`)." }, "resent_rows": { "type": "integer", "description": "Rows identical to the row before them — the same state re-sent by a source on its timer, which the raw tape carries by design. No point separates them, so they are excluded from the transition counts (`transitions_total` = `rows` − 1 − `resent_rows`) rather than counted as non-point steps. 0 on a `clean` or `recon` basis: the collapse removes them, and in a reconstruction one row IS one point so a repeat is a vendor tear and is never dropped. Added 2026-09-20." }, "server_rows": { "type": "integer", "description": "Rows carrying a server." }, "starts_at_love": { "type": "boolean", "description": "The first row is the 0-0 opening state." }, "ends_at_final": { "type": "boolean", "description": "The last row is a complete, legal final scoreline AND shows no game in progress: points at love or null, not a tiebreak in progress. A row carrying a finished spine with a game still underway (e.g. [[6,6],[3,4]] at 15-0) reads false (since 2026-09-21; before that the spine alone decided)." }, "basis": { "type": "string", "enum": [ "raw", "clean", "recon" ], "description": "Which serve was measured: `raw` | `clean` (the default read, as returned) or `recon` (the whole reconstruction, `?points=complete`)." }, "available_complete": { "type": [ "boolean", "null" ], "description": "`?points=complete` responses only. Whether a point-complete reconstruction exists for this match — never guessed. Nightly, refreshed on read when absent: the nightly ledger's verdict when it has one; when the ledger has no entry yet (a reconstruction that landed after the last nightly run) and this read served a reconstruction, it is the live verdict just measured on it (`complete`); null only when there is no ledger entry and nothing to measure. Added 2026-09-20." }, "games_short": { "type": [ "integer", "null" ], "description": "A completed game for which the tape holds fewer point transitions than that game must have contained; `> 0` forces `complete` to `false`; nothing is inferred or repaired. Counted by walking the sequence by game boundary and comparing what is held for each completed game with the FEWEST points that game can have contained given the last state it shows (from 0-0 at least 4; from 15-30 at least 5; from 40-40 at least 8; a tiebreak at least 7) — a lower bound, never an estimate. A game the tape skips whole (0-0 → 0-0 with the games counter up by one) counts; so does a game that ended with no further rows after its last stored point. The game's boundary rows are still served exactly as stored. `null` = nothing measured (an empty sequence). Added 2026-09-21." }, "games_withheld": { "type": [ "integer", "null" ], "description": "Present only when reconstructed rows are in the response. Games whose vendor point record was internally inconsistent (the recorded in-game scores do not form a legal single-point progression from 0-0 — a state repeating or moving backwards) have their in-game points withheld rather than published; the game's opening 0-0 row is still served, so the games spine stays intact. Nothing is repaired, reordered or inferred: a game is served exactly as recorded, or not at all. `> 0` means `complete` is `false`. `null` = not measured — the reconstruction predates this check, or was built from the multi-vendor union rather than a single vendor's point record. Added 2026-09-20." } } }, "HistoryPackage": { "type": "object", "description": "Manifest of one pre-built bulk package (PRO, Historical Data API Pro+, or a one-off package pass). Tape coverage is not a contiguous run of months and is still being extended backwards, so treat the packages listing as the authoritative set of periods that exist. For `kind=tape` the JSONL file holds ONE LINE PER MATCH (a whole HistoryTape object per line, coverage meta included), not one line per point; the CSV is flattened to one row per point and carries no coverage columns. Under `schema_version` 2 (since 2026-09-22) each JSONL line is exactly what `GET /history/matches/{matchId}` returns for that match on its default basis, produced by the same code: the same tape rows with the same fields as the per-match tape (`origin`, `serve`, `outcome`, `winner` beside the score columns) and the same `meta` (`coverage`, `point_source`, `enrichment`, `reconstructed_at`, `observed_span`, `tiebreaks_source`, and `meta.points` whenever the endpoint serves it), so a model that initialises its serve states from `server` / `serve` / `winner` reads them from the bulk file just as it would from the endpoint. The CSV column order is stable and grows only at the end: `match_id`, `row`, `timestamp`, `sets_p1`, `sets_p2`, `games_p1`, `games_p2`, `points_p1`, `points_p2`, `server`, `is_tiebreak`, `win_probability_p1`, `danger` — the columns every month has ever carried — then, since schema version 2, `origin`, `serve`, `outcome`, `winner`, with the same values and vocabularies as the JSONL row (a null is an empty cell); read the header, not positions, for anything past `danger`. A month may also list the complete-basis ADDENDUM files (tennis_history_points_complete_.jsonl.gz / .csv.gz, gzipped and marked by `compression`, added 2026-08-18). The two bases, plainly: the BASE files carry every match's DEFAULT read — already the complete tape for most point-complete matches — and the ADDENDUM carries, for exactly the matches whose complete point sequence exists only as the on-disk reconstruction, the same tape `?points=complete` serves (reconstruction contract: null timestamps and null model fields). Base files are never rewritten by the addendum; their sha256 values do not move. For `kind=rally` (the charted rally corpus, ULTRA) the JSONL holds one line per charted match with its full point list and the CSV one row per point, one file per YEAR. For `kind=archive` (the results archive, 1968–2022) the JSONL holds one line per archive result (the ArchiveMatch shape) and the CSV one row per result, one file per YEAR. For `kind=archive_tape` (the reconstructed 2013–2022 point-by-point tape; ULTRA, History Pro/Business, or an active one-off package window) the JSONL record is byte-for-byte what `GET /history/archive/matches/{archiveId}/tape` returns — one whole ArchiveTape object per line, `meta` included — so a parser written against one match runs over a whole year unchanged; the CSV is the flat per-row view keyed on `archive_match_id` and deliberately carries NO `timestamp`, `win_probability_p1` or `danger` column, because a column empty in 100% of a file invites the belief that it is sometimes populated. Ten periods, `period` 2013 through 2022, each with a JSONL and a CSV file, all `ready`; no earlier year exists, because no tape earlier than 2013 exists. For `kind=elo` (the as-of Elo tape; ULTRA or History Pro/Business) the JSONL holds one rating record per line — the endpoint's field set plus `archive_player_id`, the stable person key a bulk join needs — and the CSV one row per record, one file per YEAR; the files are written in primary-key order, so a rebuild of the same data is byte-identical and the published `sha256` is a real checksum.", "properties": { "period": { "type": "string", "description": "Calendar month, `YYYY-MM` — or the bare year `YYYY` on the yearly `rally`/`archive`/`elo`/`archive_tape` kinds." }, "status": { "type": "string", "enum": [ "ready" ], "description": "Only built months are listed or served." }, "match_count": { "type": [ "integer", "null" ] }, "row_count": { "type": [ "integer", "null" ] }, "files": { "type": "array", "description": "One entry per downloadable format.", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "jsonl", "csv" ] }, "filename": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "compression": { "type": "string", "enum": [ "gzip" ], "description": "Present only on compressed files (the yearly kinds and the points_complete addendum ship gzipped). `bytes` and `sha256` cover the COMPRESSED bytes — exactly what you download." } } } }, "built_at": { "type": [ "string", "null" ], "format": "date-time" }, "schema_version": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "Which shape this month's files carry (added 2026-09-22), so you can tell without opening them. `2` = a package row is the API tape row (`origin`, `serve`, `outcome`, `winner`, and the full `meta`), and the CSV carries the trailing columns. `1` = the shape every month built before 22 September 2026 carries: tape rows hold the score columns only (no `origin`, `serve`, `outcome` or `winner`; no `meta.enrichment`, `reconstructed_at` or `observed_span`), and the CSV ends at `danger`. Months built before 22 September 2026 keep this shape UNTIL THEY ARE REBUILT; the rebuild runs newest month first, then backwards, and a month's `schema_version` flips to `2` (and its `built_at` and `sha256` values move) when its turn comes. Check the manifest rather than assuming a month is one or the other: a consumer that needs the enriched fields should require `schema_version >= 2` and, for a month still at `1`, read the per-match endpoint for the matches it needs. `null` = not versioned: the non-tape kinds (`rankings`, `elo`, …)." }, "kind": { "type": "string", "enum": [ "tape", "rankings", "rally", "archive", "elo", "archive_tape" ], "description": "Present only on non-tape packages, so the shape a tape client already parses is unchanged. On a rankings package `match_count` is the number of players covered and `row_count` the number of ranking records; on a rally package the counts are charted matches and points; on an archive package the counts are archive results; on an `elo` package `row_count` is the number of rating records; on an `archive_tape` package `match_count` is the reconstructed tapes in that year and `row_count` their score rows (97,901 and 14,340,663 across the ten years)." } } }, "Coverage": { "type": "string", "enum": [ "from_start", "partial", "reconstructed", "reconstructed_partial", "none" ], "description": "How a tape came to exist, and specifically whether we WATCHED it. `from_start` — we watched this match live from 0-0; every row was committed by our own pipeline while the point was being played, so every row carries a real timestamp. It is a statement about how the rows were obtained, NOT a synonym for \"complete\". `partial` — we watched it, but recording began after play had started and no reconstruction is available to repair the opening. `reconstructed` — the tape opens with rows expanded after the fact from a finished-match point-by-point record: either the whole tape (we never watched the match) or its unwatched opening followed by what we did watch. True about the score, silent about the clock. `reconstructed_partial` — as `reconstructed`, AND the reconstruction is known not to cover the whole match. That happens two ways: it OPENS AFTER 0-0 (the upstream record begins mid-match), or it STOPS SHORT of the official final score (the record truncated, usually by the deciding game). Every row is still a point somebody recorded — nothing is synthesised to close either gap — but the match is NOT complete and must not be backtested as if it were. `none` — no rows; the match was on the calendar and was neither watched nor reconstructable. This vocabulary describes the 2023+ tape. The 2013–2022 archive tape (`ArchiveTape`) reuses it restricted to `reconstructed` and `reconstructed_partial`, and derives the second DIFFERENTLY: there a per-GAME tape carries that label however complete it is — see `ArchiveTape.meta.coverage` before reading it the same way." }, "CoverageRollup": { "type": "object", "description": "The measured completeness rollup — what the archive HOLDS, per tour × draw bucket, as of the artifact's own build clock.", "properties": { "as_of": { "type": "string", "format": "date-time", "description": "Equal to `built_at`, verbatim — the artifact's own clock, and the date to quote with every number in this response." }, "built_at": { "type": "string", "format": "date-time", "description": "When the rollup was built (UTC)." }, "ledger_max_computed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The newest underlying per-match measurement in the completeness ledger." }, "method": { "type": "string", "description": "The full measurement rule for point_complete, in one paragraph — every number carries its own definition." }, "buckets": { "type": "object", "description": "One CoverageBucket per tour × draw bucket (`atp_singles` … `juniors_doubles`, plus `other`). A bucket with zero completed matches is OMITTED rather than emitted as zeros — read a missing key as \"nothing to count\", not an error.", "additionalProperties": { "$ref": "#/components/schemas/CoverageBucket" } }, "totals": { "$ref": "#/components/schemas/CoverageBucket" } } }, "CoverageBucket": { "type": "object", "description": "The five verifiable numbers for one bucket.", "properties": { "completed": { "type": "integer", "description": "Completed matches in the bucket." }, "any_tape": { "type": "integer", "description": "Matches with at least one tape row on any basis." }, "point_complete": { "type": "integer", "description": "Measured point-complete on the BEST basis — what `?points=complete` can serve." }, "complete_on_default_read": { "type": "integer", "description": "Point-complete on the default read alone. The difference against `point_complete` is the set of matches where `?points=complete` is load-bearing." }, "share": { "type": [ "number", "null" ], "description": "point_complete / completed. Null on an empty bucket." } } }, "HistoryMatch": { "allOf": [ { "$ref": "#/components/schemas/Match" }, { "type": "object", "properties": { "tape": { "type": "object", "description": "What point-by-point data we hold for this match.", "properties": { "coverage": { "$ref": "#/components/schemas/Coverage" }, "rows": { "type": "integer", "description": "Rows we OBSERVED (watched live). This is not the length of the tape you will be served: a reconstructed or mixed tape also includes reconstructed rows, and for a partially-watched match only a prefix of the reconstruction is spliced in front. Use `meta.rows` on the per-match tape for the served length." }, "reconstructed_rows": { "type": "integer", "description": "Reconstructed rows available for this match." }, "model_rows": { "type": "integer", "description": "How many of the OBSERVED rows carry a non-null `win_probability_p1`. The model stamp is best-effort and no coverage value — `from_start` included — implies it; read this number to select tapes the model actually scored." }, "points_complete": { "type": [ "boolean", "null" ], "description": "Measured point-completeness, best basis: true when the served tape OR an on-disk reconstruction of the match measured point-complete (fetch the latter with `?points=complete` on the per-match tape); null when the match has not been measured yet — never a guess. Since 2026-09-20 the served-tape leg judges the same raw sequence (provable re-sends dropped) that the per-match read serves and measures in `meta.points`, so the two agree by construction; a row scored before the switch may still disagree until the nightly re-score reaches it (see `points_basis`). Read from a per-match ledger reconverged nightly. Present where enabled." }, "points_complete_default": { "type": [ "boolean", "null" ], "description": "WHICH measurement produced `points_complete` — this one is the served tape, measured on `points_basis`. Since 2026-09-20 that basis is the same raw sequence the per-match read serves (re-sends dropped), so this field and that read's `meta.points.complete` agree by construction instead of disagreeing on a collapse the read never served. Null when that basis was not measured. Added 2026-09-20 after a consumer filtered on `points_complete=true`, fetched a match and read `meta.points.complete: false`: both answers were honest about their own sequence, and nothing in the payload said which sequence each had judged. Present where enabled." }, "points_complete_recon": { "type": [ "boolean", "null" ], "description": "The other half of `points_complete`: the on-disk reconstruction, which you fetch with `?points=complete` on the per-match tape. Null when no reconstruction existed when the ledger last ran. A complete reconstruction is a different object from a complete observed tape — every row carries a null `timestamp` and null model fields, because neither ever existed for it. Present where enabled." }, "points_basis": { "type": [ "string", "null" ], "enum": [ "clean", "raw", null ], "description": "Which sequence `points_complete_default` judged — `raw`, the same sequence the per-match read serves (provable re-sends dropped, exactly as that read's `meta.points` judges it), for an observed tape and a served reconstruction alike. `clean` — the collapsed one row per distinct state, still obtainable with `?sequence=clean` as a request option — appears only on a row scored before 2026-09-20 that the nightly re-score has not yet reached. Null when not measured. Present where enabled." }, "completeness": { "type": [ "number", "null" ], "description": "The better of the two measured completeness fractions (0..1, lower-bound denominator — see the per-match tape's `meta.points`). Null when not measured. Present where enabled." }, "starts_at_love": { "type": [ "boolean", "null" ], "description": "Whether a measured basis OPENS at the 0-0 state — the SAME best-basis rule as points_complete: true when either basis starts at love, so if any on-disk sequence opens at 0-0 you can obtain one that does. Null when the match has not been measured. Present where enabled." }, "computed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the ledger last measured this match, UTC with a trailing `Z` — the same projection every other clock in this payload uses, so it can be diffed against `meta.generated_at` or a row's `timestamp` without normalising it by hand first. Every field in this block is a nightly-reconverged cache; this is the as-of to quote with any of them. Null when the match has not been measured. Present where enabled." } } } } } ] }, "Usage": { "type": "object", "properties": { "principal": { "type": "string", "description": "Opaque ref to your own key" }, "tier": { "type": "string", "enum": [ "free", "basic", "pro", "ultra" ] }, "base_tier": { "type": "string", "description": "Subscription tier; equals `tier` unless a temporary grant is active" }, "tier_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a temporary tier grant reverts, else null" }, "channel": { "type": "string" }, "limits": { "type": "object", "properties": { "per_minute": { "type": [ "integer", "null" ] }, "per_day": { "type": [ "integer", "null" ] } } }, "today": { "type": "object", "properties": { "calls": { "type": "integer" }, "errors": { "type": "integer" }, "remaining_day": { "type": [ "integer", "null" ], "description": "Requests still SERVABLE today: the day allowance less SERVED calls (`calls - errors`). Refused requests never spend the allowance, so this does not fall when a `429`, `403` or `404` is returned. Null when the tier carries no day cap." } } }, "history": { "type": "array", "description": "Last 30 days, oldest first", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "calls": { "type": "integer" }, "errors": { "type": "integer" } } } }, "as_of": { "type": "string", "format": "date-time" } } }, "MatchStatisticsSide": { "type": "object", "description": "One player's in-play statistics, in TWO families that are deliberately not merged. The fields at this level are DERIVED from the point-by-point record. `measured` holds counts taken upstream, including the ones no point record can yield: aces, double faults, the serve split, winners and unforced errors. Both families name some of the same quantities, computed two entirely different ways — that is a cross-check, not a duplication to be collapsed.", "properties": { "measured": { "$ref": "#/components/schemas/MatchStatisticsMeasured" }, "service_games_played": { "type": "integer" }, "service_games_won": { "type": "integer" }, "hold_pct": { "type": [ "integer", "null" ], "description": "null when no service game was played — never 0, so a present 0 is a real measured zero" }, "return_games_played": { "type": "integer" }, "return_games_won": { "type": "integer" }, "break_pct": { "type": [ "integer", "null" ] }, "break_points_faced": { "type": "integer" }, "break_points_saved": { "type": "integer" }, "break_points_saved_pct": { "type": [ "integer", "null" ] }, "break_points_played": { "type": "integer" }, "break_points_converted": { "type": "integer" }, "break_points_converted_pct": { "type": [ "integer", "null" ] }, "service_points_played": { "type": "integer" }, "service_points_won": { "type": "integer" }, "service_points_won_pct": { "type": [ "integer", "null" ] }, "return_points_played": { "type": "integer" }, "return_points_won": { "type": "integer" }, "return_points_won_pct": { "type": [ "integer", "null" ] }, "points_played": { "type": "integer" }, "points_won": { "type": "integer" } } }, "MatchStatisticsMeasured": { "type": "object", "description": "Measured counting statistics for one player. These are COUNTED upstream, not derived from the point record — which is why they can include aces and double faults, and the derived fields above cannot. They are MATCH TOTALS only — one whole-match rollup per player; there are no per-set measured statistics.\nEVERY FIELD IS OPTIONAL AND AN ABSENT FIELD IS OMITTED, never zero-filled — absent means NOT MEASURED, and a present 0 is a real measured zero. Do not assume a fixed shape; read the keys you are given. Measured over 24,552 stored payloads (2026-07-31), coverage falls into three tiers:\nTIER 1 — present on 98.6-100% of payloads, on every tour including ITF: aces, double faults, points won, service and return points won, break points won, service games won, longest point and game runs, return points.\nTIER 2 — present on essentially all ATP, WTA and Challenger matches and on NO ITF singles match: the first and second serve split, break points saved, tiebreaks won, games won, service games played.\nTIER 3 — the winners / unforced-errors / forced-errors family, in total and by shot type. Historically delivered on ~43% of ATP singles, ~24% of WTA singles and ~47% of tour doubles, and on NONE of Challenger, ITF or juniors — those zeros are hard, not sampling noise. The upstream feed has NOT DELIVERED this group at all since 2026-07-12 (measured 2026-08-17: 0 of 4,513 August payloads carry it, live ATP Masters included), so expect it absent on current matches until the upstream feed resumes it.\nA `_of` suffix is the denominator of its base field and a `_pct` suffix is the percentage, recomputed from the two counts rather than read from the upstream rounding.", "properties": { "aces": { "type": [ "integer", "null" ] }, "break_points_won": { "type": [ "integer", "null" ] }, "double_faults": { "type": [ "integer", "null" ] }, "first_return_points_won": { "type": [ "integer", "null" ] }, "first_return_points_won_of": { "type": [ "integer", "null" ] }, "first_return_points_won_pct": { "type": [ "integer", "null" ] }, "max_games_in_row": { "type": [ "integer", "null" ] }, "max_points_in_row": { "type": [ "integer", "null" ] }, "points_won": { "type": [ "integer", "null" ] }, "return_points_won": { "type": [ "integer", "null" ] }, "second_return_points_won": { "type": [ "integer", "null" ] }, "second_return_points_won_of": { "type": [ "integer", "null" ] }, "second_return_points_won_pct": { "type": [ "integer", "null" ] }, "service_games_won": { "type": [ "integer", "null" ] }, "service_points_won": { "type": [ "integer", "null" ] }, "break_points_saved": { "type": [ "integer", "null" ] }, "break_points_saved_of": { "type": [ "integer", "null" ] }, "break_points_saved_pct": { "type": [ "integer", "null" ] }, "first_serve_points_won": { "type": [ "integer", "null" ] }, "first_serve_points_won_of": { "type": [ "integer", "null" ] }, "first_serve_points_won_pct": { "type": [ "integer", "null" ] }, "first_serves_in": { "type": [ "integer", "null" ] }, "first_serves_in_of": { "type": [ "integer", "null" ] }, "first_serves_in_pct": { "type": [ "integer", "null" ] }, "games_won": { "type": [ "integer", "null" ] }, "second_serve_points_won": { "type": [ "integer", "null" ] }, "second_serve_points_won_of": { "type": [ "integer", "null" ] }, "second_serve_points_won_pct": { "type": [ "integer", "null" ] }, "second_serves_in": { "type": [ "integer", "null" ] }, "second_serves_in_of": { "type": [ "integer", "null" ] }, "second_serves_in_pct": { "type": [ "integer", "null" ] }, "service_games_played": { "type": [ "integer", "null" ] }, "tiebreaks_won": { "type": [ "integer", "null" ] }, "backhand_errors": { "type": [ "integer", "null" ], "description": "Forced errors off the backhand." }, "backhand_unforced_errors": { "type": [ "integer", "null" ], "description": "Unforced errors off the backhand." }, "backhand_winners": { "type": [ "integer", "null" ], "description": "Winners off the backhand." }, "drop_shot_unforced_errors": { "type": [ "integer", "null" ], "description": "Unforced errors on the drop shot." }, "drop_shot_winners": { "type": [ "integer", "null" ], "description": "Winners on the drop shot." }, "errors_total": { "type": [ "integer", "null" ], "description": "The total of FORCED errors, not of all errors. Verified over 3,766 stored payload sides (June-July 2026): it equals the forehand + backhand + return + overhead error sum in 96.2% of sides, it is SMALLER than `unforced_errors_total` in 11.7% of sides (impossible for a superset), and per-match points accounting — points won = own winners + opponent forced errors + opponent unforced errors — closes with median residual 0 over 367 matches only under the forced reading. Total errors = `errors_total` + `unforced_errors_total`; there is no separate forced-errors field to wait for, because these fields ARE the forced counts." }, "forehand_errors": { "type": [ "integer", "null" ], "description": "Forced errors off the forehand." }, "forehand_unforced_errors": { "type": [ "integer", "null" ], "description": "Unforced errors off the forehand." }, "forehand_winners": { "type": [ "integer", "null" ], "description": "Winners off the forehand." }, "groundstroke_errors": { "type": [ "integer", "null" ], "description": "`forehand_errors` + `backhand_errors` — a rollup of the two, not an additive extra." }, "groundstroke_unforced_errors": { "type": [ "integer", "null" ], "description": "Unforced errors off the ground strokes." }, "groundstroke_winners": { "type": [ "integer", "null" ], "description": "Winners off the ground strokes." }, "lob_unforced_errors": { "type": [ "integer", "null" ], "description": "Unforced errors on the lob." }, "lob_winners": { "type": [ "integer", "null" ], "description": "Winners on the lob." }, "overhead_errors": { "type": [ "integer", "null" ], "description": "Forced errors on the overhead — the upstream's overhead-stroke count." }, "overhead_winners": { "type": [ "integer", "null" ], "description": "Winners on the overhead." }, "return_errors": { "type": [ "integer", "null" ], "description": "Forced errors on the return." }, "return_winners": { "type": [ "integer", "null" ], "description": "Winners on the return." }, "unforced_errors_total": { "type": [ "integer", "null" ], "description": "The total of unforced errors. Total errors = `errors_total` + `unforced_errors_total`." }, "volley_unforced_errors": { "type": [ "integer", "null" ], "description": "Unforced errors on the volley." }, "volley_winners": { "type": [ "integer", "null" ], "description": "Winners on the volley." }, "winners_total": { "type": [ "integer", "null" ], "description": "Total winners." } } }, "MatchStatisticsFreshness": { "type": "object", "description": "Per-family coverage and age. Branch on this rather than on the top-level `coverage`, which only summarises the response. The two ages use DIFFERENT clocks and must not be compared: `derived.age_seconds` is relative to the newest score row (between points there is no new score either, so wall-clock age would report staleness that does not exist), while `measured.age_seconds` is wall clock, because those are fetched on a fixed cadence.", "properties": { "measured_divergence": { "type": [ "object", "null" ], "description": "Null when the families agree. Otherwise why the measured values were withheld, with both match states.", "properties": { "reason": { "type": "string" }, "games_in_statistics": { "type": "integer" }, "games_in_score": { "type": "integer" }, "delta_games": { "type": "integer", "description": "positive = statistics ahead of the score, which staleness cannot cause" }, "detail": { "type": "string" } } }, "derived": { "$ref": "#/components/schemas/MatchStatisticsFamily" }, "measured": { "$ref": "#/components/schemas/MatchStatisticsFamily" } } }, "MatchStatisticsFamily": { "type": "object", "properties": { "coverage": { "type": "string", "enum": [ "live", "final", "stale", "none", "diverged" ], "description": "`final` = the closing figures of a completed match. A finished match cannot be \"stale\", so on `final` the family's `age_seconds` is null; `as_of` still says when the last point/fetch was recorded." }, "as_of": { "type": [ "string", "null" ] }, "age_seconds": { "type": [ "integer", "null" ] }, "describes": { "type": [ "object", "null" ], "description": "The match state these statistics describe, per upstream. `age_seconds` says when we fetched; this says WHAT we fetched. Null when unavailable.", "properties": { "games_p1": { "type": "array", "items": { "type": "integer" } }, "games_p2": { "type": "array", "items": { "type": "integer" } }, "total_games": { "type": "integer" } } } } }, "MatchStatistics": { "type": "object", "properties": { "match_id": { "type": "integer" }, "coverage": { "type": "string", "enum": [ "live", "final", "stale", "none", "diverged" ] }, "as_of": { "type": [ "string", "null" ], "description": "When the underlying record was last updated (UTC)" }, "age_seconds": { "type": [ "integer", "null" ], "description": "Behind the newest SCORE row, not the wall clock" }, "games_counted": { "type": "integer" }, "tiebreak_games_excluded": { "type": "integer", "description": "Tiebreaks are excluded — the live record collapses a whole tiebreak onto one entry" }, "inconsistent_games_excluded": { "type": "integer", "description": "Games whose recorded outcome is neither a legal hold nor a legal break" }, "sets_covered": { "type": "array", "items": { "type": "integer" } }, "freshness": { "$ref": "#/components/schemas/MatchStatisticsFreshness" }, "detail": { "type": "string", "description": "Present only when coverage is none" }, "players": { "type": [ "object", "null" ], "properties": { "p1": { "$ref": "#/components/schemas/MatchStatisticsSide" }, "p2": { "$ref": "#/components/schemas/MatchStatisticsSide" } } } } }, "RankingRecord": { "type": "object", "description": "One ranking record in force at the requested instant. `system` is always explicit and the systems are never collapsed into a single \"rank\" — they are not comparable. ATP/WTA and the ITF circuits populate rank+points; UTR populates rating and leaves rank/points null, because UTR is a rating and has no rank.", "properties": { "player_id": { "type": [ "integer", "null" ], "description": "Null only on listing rows for players outside our roster — the listing is kept independent of the roster precisely so a top-N has no silent holes. Always present on per-player records for the official systems and UTR. For `elo` it is also null on rows for the ~62,000 rated people with no roster row — normal, not an error; `player_name` is always populated, and `archive_player` fetches that person directly." }, "player_name": { "type": [ "string", "null" ], "description": "The name as the ranking publisher printed it — present on listing rows (where `player_id` may be null), absent on per-player records." }, "system": { "type": "string", "enum": [ "atp", "wta", "itf_jt", "itf_mt", "itf_wt", "utr", "elo", "atp_doubles", "wta_doubles" ] }, "tour": { "type": [ "string", "null" ] }, "rank": { "type": [ "integer", "null" ], "description": "Null for UTR. Null for `elo` in per-player mode too — an Elo has no global rank at a past instant until you say which field and which activity window you mean, and the per-player read is given neither. In `elo` listing mode it is the position in the qualified field of THAT call." }, "points": { "type": [ "integer", "null" ], "description": "Null for UTR and for `elo` — both are ratings, and neither has points." }, "surface": { "type": "string", "enum": [ "overall", "hard", "clay", "grass" ], "description": "`elo` only, and absent on every other system. Which of the four independent ladders this rating is. A ladder the player has never played is omitted from the response rather than substituted with another." }, "matches": { "type": [ "integer", "null" ], "description": "`elo` only, and absent on every other system. Cumulative matches on THAT ladder at that date — not the player's career total. Every ladder starts at 1500, so this is what tells you whether a rating is an assessment or a cold start, and it is the number `min_matches` filters on." }, "previous_rank": { "type": [ "integer", "null" ], "description": "The rank at the immediately preceding snapshot week (ATP/WTA only; null when no prior week is held, and always null for ITF/UTR)." }, "rank_movement": { "type": [ "integer", "null" ], "description": "The circuit's own signed weekly movement (ITF systems only; null elsewhere)." }, "rating": { "type": [ "number", "null" ], "description": "UTR and `elo` only; null elsewhere. For `elo` this is the Elo itself, on our own scale, which is not comparable with Elo published anywhere else." }, "effective_date": { "type": [ "string", "null" ], "format": "date", "description": "The publication week this record took effect. For records ingested live rather than from the official weekly publication this is bucketed to the observed week, so it can sit up to six days later than the moment the value actually took effect; where both exist for one week the official publication is served." }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RankingListMeta": { "allOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "object", "properties": { "coverage": { "type": "object", "description": "What resolved against what was asked. Read it before trusting an empty result — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29); nothing earlier can be reconstructed, so a request before `oldest_available` correctly returns nothing for those systems.", "properties": { "as_of": { "type": [ "string", "null" ], "format": "date" }, "effective_date": { "type": [ "string", "null" ], "format": "date", "description": "Listing mode. For the official systems, the published week the table is from. For `elo`, the as-of instant the leaderboard was resolved at (each row carries its own `effective_date`, since a sparse tape moves per player)." }, "players_requested": { "type": "integer", "description": "Per-player mode only." }, "players_resolved": { "type": "integer", "description": "Per-player mode only." }, "systems_requested": { "type": "array", "items": { "type": "string" } }, "systems_resolved": { "type": "array", "items": { "type": "string" } }, "oldest_available": { "type": "object", "additionalProperties": { "type": [ "string", "null" ], "format": "date" }, "description": "Earliest effective date held, per requested system." }, "newest_available": { "type": "object", "additionalProperties": { "type": [ "string", "null" ], "format": "date" }, "description": "Present only when `elo` was requested. The NEWEST effective date the Elo tape holds. The corpus behind it is fixed and no longer receives new results, so this date does not advance and will keep receding from today — that is a property of a historical tape, not a fault. Read it before treating an Elo leaderboard as a current one." }, "tour": { "type": [ "string", "null" ], "description": "Present only when `elo` was requested — which walk answered." }, "surface": { "description": "Present only when `elo` was requested. The ladder (listing) or the list of ladders (per-player) the response covers." }, "players_rated": { "type": "integer", "description": "Present only when `elo` was requested. People with at least one rating in the tape." }, "players_linked": { "type": "integer", "description": "Present only when `elo` was requested. How many of those have a row in our player roster, and therefore can be reached with `player`. The rest are reachable with `archive_player` and appear on the leaderboard with a null `player_id` and their name. The gap between these two numbers is large and is reported rather than buried." }, "qualified": { "type": "object", "description": "Present only on an `elo` listing. The two filters that DEFINE the field this table ranks. A top-N is not quotable without them — change either and it is a different top-N, and neither is more correct than the other.", "properties": { "activity_weeks": { "type": "integer" }, "min_matches": { "type": "integer" } } }, "model": { "type": "object", "description": "Present only when `elo` was requested. What the numbers ARE.", "properties": { "name": { "type": "string" }, "start_rating": { "type": "number" }, "k_base": { "type": "number" }, "publication_lag_days": { "type": "integer", "description": "A result becomes effective this many days after its tournament WEEK begins. The corpus dates a match by its tournament start, so without the lag a Slam final would be visible under the Monday the Slam began. The lag clears the longest event in tennis, so the failure direction is staleness and never look-ahead." }, "built_at": { "type": [ "string", "null" ], "format": "date-time" }, "note": { "type": "string" } } } } } } } ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "score", "break_point" ] } }, "enabled": { "type": "boolean", "description": "Set to false automatically after 25 consecutive delivery failures — delete and re-register to resume." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "secret": { "type": "string", "description": "Present ONLY on the 201 registration response — shown exactly once" }, "secret_note": { "type": "string" } } }, "BreakPoint": { "type": "object", "description": "WebSocket `break_point` frame (ULTRA). Pushed the instant a break point arises, but only when the subscription named `break_point` in its `signals`. Fields sit inline (no nested score object); `prob_swing` mirrors the REST score's `danger`. `server` is the player serving, `returner` the one holding the break point(s).", "properties": { "type": { "type": "string", "const": "break_point" }, "match_id": { "type": "integer" }, "server": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "returner": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "break_points": { "type": [ "integer", "null" ], "description": "How many break points are live at once (1-3)." }, "set": { "type": [ "integer", "null" ] }, "game": { "type": [ "integer", "null" ] }, "point": { "type": [ "string", "null" ] }, "win_probability_p1": { "type": [ "number", "null" ] }, "prob_swing": { "type": [ "number", "null" ] }, "server_side_favoured": { "type": [ "boolean", "null" ] }, "ts": { "type": [ "string", "null" ], "format": "date-time" } } }, "BreakPointResult": { "type": "object", "description": "WebSocket `break_point_result` frame (ULTRA): a break point just resolved. `outcome` is `held` (server saved it) or `broken` (returner converted); `win_probability_p1_after` is p1's win probability once the game closed.", "properties": { "type": { "type": "string", "const": "break_point_result" }, "match_id": { "type": "integer" }, "server": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "outcome": { "type": "string", "enum": [ "held", "broken" ] }, "win_probability_p1_after": { "type": [ "number", "null" ] }, "ts": { "type": [ "string", "null" ], "format": "date-time" } } }, "LivePoint": { "type": "object", "description": "One PLAYED point of a live match — the expanded score state AFTER the point. `seq` is per-match, monotonic and never skips a value: the ordering, dedup and resume key across the WS frames, the webhook deliveries and the REST catch-up read. `ts` is CAPTURE time (when our pipeline committed the state), never a per-point clock — no feed asserts one and we fabricate none.", "properties": { "seq": { "type": "integer", "description": "Per-match monotonic position 1..N — dedup and resume on this." }, "set": { "type": [ "integer", "null" ] }, "game": { "type": [ "integer", "null" ], "description": "Game within the current set — 13 for a 6-6 tiebreak." }, "number": { "type": [ "integer", "null" ], "description": "Points already recorded in this game at this state — 0 for a game's opening state, and **null when we joined the game already in progress**: how many points it holds is not derivable from the score (the deuce zone maps many ordinals onto one score) and is never guessed. `(set, game, number)` is NOT a unique key — a game re-expanded by a second source legitimately re-asserts ordinals it already holds, so the same tuple can name more than one row. `seq` is the only unique, stable per-row key." }, "tiebreak": { "type": "boolean" }, "server": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "Server of the point played FROM this state; null when the feed omits it." }, "winner": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "Who won the point that produced this state — null when not attributable to a single point, never guessed." }, "score": { "type": "object", "description": "In-game score AFTER the point ('0'/'15'/'30'/'40'/'AD'; the running tiebreak count as integer strings when `tiebreak` is true).", "properties": { "p1": { "type": [ "string", "null" ] }, "p2": { "type": [ "string", "null" ] } } }, "sets": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "games": { "type": "array", "description": "`[games_p1, games_p2]`; each a per-set list, frozen at the pre-breaker score during a tiebreak.", "items": { "type": "array", "items": { "type": "integer" } } }, "ts": { "type": [ "string", "null" ], "format": "date-time", "description": "Capture time (UTC) — when our pipeline committed this state. Null on every frame of a `reconstruction`-basis page — the recorded sequence carries no per-point clock and none is fabricated. On the match-closing row of a completed match it is the instant the final score was observed." }, "serve": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ], "description": "Added 2026-09-12. The serve the point was played on (1 first, 2 second) as an outside source states it, joined onto the row by exact state. Null = not stated for this point; never inferred. A source point whose serve number and outcome contradict each other (a double fault stated on a first serve) is served untagged — `serve` and `outcome` both null — rather than tagged wrongly; nothing is corrected to a second serve (since 2026-09-21). Lands a few seconds after the point's own frame (see the `point_update` frame). Stated on the ATP main tour, ATP Challenger, WTA 1000/500/250/125, UTR and the top Davis Cup tiers; not stated on the ITF World Tennis Tour, nor in any doubles draw. EVERY COUNT BELOW IS WHAT THIS ENDPOINT PUBLISHES, not what we store, and on completed matches the two differ (corrected 2026-09-23; the figures published before that date were counted in our own tables and overstated what a reader could fetch). A completed match whose stored per-point stream does not pass our quality bar is served as a measured-complete RECONSTRUCTION instead, and a reconstruction carries no clock and no tags at all — so per-match tag coverage on completed matches is lower, often much lower, than the share of matches a source tagged. `basis` on this response names which one you were given. Team ties, re-measured 2026-09-23 over completed matches with a per-point stream since 2026-09-12: Davis Cup World Group publishes `serve` on 2 of 22 and World Group I on 1 of 42, while World Group II publishes it on 0 of 38 — against 22 of 22 and 41 of 42 respectively in storage, which is the gap this paragraph is about. Qualifying draws are covered like their own main draw, not excluded, and land in the same place their main draw does: WTA qualifying 18 of 48 against 50 of 88 in the WTA main draw, ATP Challenger qualifying (`tier: challenger_*`) 137 of 197 against 221 of 285, and WTA 125 qualifying (`tier: wta_125`, also carried under `tour: challenger`) 47 of 63 against 117 of 147. Read `enrichment` per match — it is the only per-match answer, none of this is a promise about a match not yet played. Since 2026-09-22, on the tours whose own point-by-point console we read (ATP 250/500/1000, ATP Challenger, WTA 1000/500/250/125), a COMPLETED match is re-joined after the match against the console's complete sequence by the same exact-state rule, so a completed match's serve/outcome coverage exceeds what was captured live — the tags arrive as `point_update` frames and `tagged_at` revisions like any other." }, "outcome": { "type": [ "string", "null" ], "enum": [ "ace", "double_fault", "winner", "forced_error", "unforced_error", null ], "description": "Added 2026-09-12. How the point ended, as an outside source states it. ATP 250 / 500 / 1000: serve stated, outcome full (ace, double fault, winner, forced error, unforced error) from the tour's own per-point console. Grand Slams and Davis Cup are not on that console, so `outcome` reads null there — but `serve` comes from a different source and IS stated on them, so those matches are not blanket-null; read `enrichment` per match. First measured on tour events from the week of 2026-09-22 — before that, no tour event had been played since the source went live on 2026-09-12. ATP Challenger — `tour: challenger` with a `challenger_*` tier — states all five. `tour: challenger` also carries the WTA 125 events (`tier: wta_125`), and those state ace and double fault only, so read `tier` rather than `tour` to tell the two apart. The ITF World Tennis Tour: ace and double fault. WTA 1000/500/250/125: ace and double fault where the tour's console reports the match — read the page's `enrichment` per match. Grand Slams and UTR: none. ITF World Tennis Tour DOUBLES draws state ace and double fault on a growing minority of matches — the tags first reached a doubles row on 2026-09-23 and the endpoint published them on 104 of 596 completed doubles matches (17%) measured 2026-09-29, so read `enrichment` per match here and do not plan a corpus on the draw. Every other doubles draw (ATP, WTA and Challenger): none, measured 0 of 371 in the same window. Qualifying draws mostly follow their own tour, and the one real gap is on the WTA main tour, not on Challenger. EVERY COUNT BELOW IS WHAT THIS ENDPOINT PUBLISHES rather than what we store (corrected 2026-09-23 — see the note on `serve` above: a completed match served on the `reconstruction` basis carries no tags, so the published share is below the share we hold). Re-measured 2026-09-23 over completed matches carrying a per-point stream since 2026-09-12: ATP qualifying publishes outcome on 16 of 16 and ATP Challenger qualifying on 134 of 197, both the full five; ITF qualifying publishes aces and double faults on 181 of 215 men's and 142 of 176 women's, and WTA 125 qualifying on 30 of 63 — while WTA main-tour qualifying publishes it on 5 of 48, against 47 of 88 in the same events' main draws. Read `enrichment` per match rather than inferring a draw's coverage from its tour. Null = not stated. A source point whose serve number and outcome contradict each other (a double fault stated on a first serve) is served untagged — `serve` and `outcome` both null — rather than tagged wrongly (since 2026-09-21). Since 2026-09-22, on the tours whose own point-by-point console we read (ATP 250/500/1000, ATP Challenger, WTA 1000/500/250/125), a COMPLETED match is re-joined after the match against the console's complete sequence by the same exact-state rule, so a completed match's coverage exceeds what was captured live — collect the late tags with `?changed_since=` or the `point_update` frame." }, "tagged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Added 2026-09-20. When `serve`/`outcome` landed on this row (UTC); null while no tag has — on every `reconstruction`-basis frame, on the match-closing row, and on any row no source tagged. Tags land a few seconds after the row itself, so a row's `tagged_at` is later than its `ts`; `changed_since` selects on either." }, "tiebreak_final": { "type": [ "array", "null" ], "items": { "type": "integer" }, "minItems": 2, "maxItems": 2, "description": "Added 2026-09-23. The breaker's closing score, in our player order, e.g. `[7, 5]`. Present ONLY on the row that closes a tiebreak set — the set roll-up (`tiebreak` false, the set banked 7-6, `score` 0-0), which is the row carrying the breaker's winning point, every row being the state after a point. Absent on every other row, including the breaker rows themselves. Exact when the previous row is the decided score or one point from it (6-5 for the set's winner gives `[7, 5]`); otherwise taken from the match's recorded tiebreak finals, the same finals `GET /history/matches/{matchId}` publishes as `tiebreaks`; null when neither can state it. Never guessed. A page that *starts* on a roll-up row (an `after_seq` landing exactly there) reads the one row before your page, so the value does not depend on where the page was cut (since 2026-09-24; before that such a page used the recorded finals alone, and so read null on a set that closed while the match was still live). The deciding set of a match-tiebreak format is judged under the 10-point rule." } } }, "PointUpdate": { "type": "object", "description": "Added 2026-09-12. Pushed on the point opt-in (`signals:[\"points\"]`, channels `point:match:{id}` / `point:slate`) when a point's `serve` / `outcome` land after its `point` frame went out. Apply to the row with that `seq`; nothing else on the point changes.", "properties": { "type": { "type": "string", "enum": [ "point_update" ] }, "match_id": { "type": "integer" }, "seq": { "type": "integer" }, "serve": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "ace", "double_fault", "winner", "forced_error", "unforced_error", null ] } } }, "MatchPoints": { "type": "object", "description": "One page of a match's per-point stream, seq order. `basis` says which base served it: the persisted live stream rows, or — for a completed match where a measured-complete recorded sequence exists — that complete sequence projected into point frames.", "properties": { "match_id": { "type": "integer" }, "pbp_coverage": { "type": "string", "enum": [ "point", "game" ], "description": "`point` = a per-point stream has DELIVERED for this match (a played point past the seq-1 opener); `game` = no played point has arrived — only the snapshot score path covers it, or the stream holds only its opener so far (an answer, not an error; flips to `point` on the first played point — gate on `last_seq > 1`)." }, "quality": { "type": "string", "enum": [ "clean", "revised" ], "description": "`revised` = the upstream feed rewrote an already-served prefix at least once during this match; served rows are never edited." }, "enrichment": { "type": "object", "description": "Added 2026-09-12. What an outside source has stated for THIS match so far — `serve`: stated | none; `outcome`: full | ace_double_fault | none. Read it before building on the fields; it is never a promise about the rest of the match.", "properties": { "serve": { "type": "string", "enum": [ "stated", "none" ] }, "outcome": { "type": "string", "enum": [ "full", "ace_double_fault", "none" ] } } }, "covers_from_start": { "type": [ "boolean", "null" ], "description": "Whether the persisted stream OPENS at the match's 0-0 opener — seq 1 exists and is the love-love state — i.e. whether replaying from `after_seq=0` yields the whole match or joins it mid-play. Null when the match has no rows at all (nothing to judge — null means not measured, never \"no\")." }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/LivePoint" } }, "last_seq": { "type": "integer", "description": "The resume cursor — pass as `after_seq` to continue." }, "has_more": { "type": "boolean" }, "basis": { "type": "string", "enum": [ "live", "reconstruction" ], "description": "Which base served this page. `live` = the persisted live stream rows, served whenever the stream is complete, or tagged and legal end to end (a projection carries no clock and no tag, so the stream is strictly more information); `reconstruction` = the complete recorded point sequence of a finished match, projected into point frames at read time, served only when the stream falls short (see `basis_reason`) — includes the match-closing point, `seq` contiguous 1..N, `ts` null on every frame. The two bases are never interleaved." }, "basis_reason": { "type": "string", "enum": [ "stream_absent", "stream_incomplete", "stream_illegal" ], "description": "Added 2026-09-21. Present on the `reconstruction` basis only — why the stored live stream was not served. `stream_absent` = no stream rows; `stream_incomplete` = the stream is legal but does not measure complete (joined mid-match or stopped short) and carries no tags; `stream_illegal` = at least one transition is not attributable to one point (a gap or a torn row). A stream that is complete, or tagged and legal end to end, is always served (basis `live`) and this key is absent." }, "ends_at_final": { "type": "boolean", "description": "Added 2026-09-20. Whether the sequence served ends on the match-closing point — the state after the match-winning point: `number` 0, score 0-0, `server` null, `winner` the match winner. On a completed match served on the `live` basis that row is appended at read time from the stored stream's last row and the observed final score, and only when the two are one point apart (when the match ends in a tiebreak, the set roll-up after the decisive tiebreak row: `tiebreak` false, the set banked 7-6, the same `winner`); false when the match is completed but the stream stops short of it (a retirement or walkover, a truncated capture, or a closer that cannot be stated as one point, such as a 10-point match tiebreak), and always false on a live match. On the `reconstruction` basis it is judged from the last projected frame." } } }, "PointFrame": { "type": "object", "description": "WebSocket `point` frame (ULTRA, opt-in via `signals: [\"points\"]`; also the webhook `point` event body): one PLAYED point of a subscribed match. `seq` is arrival order, not match order — dedup/resume on it, and sort by `(set, game, number)` to replay in playing order (that tuple may repeat or carry a null `number`; it orders points, it does not identify them). Best-effort, NO replay — catch up via `GET /matches/{matchId}/points?after_seq=`.", "properties": { "type": { "type": "string", "const": "point" }, "published_at": { "type": "string", "format": "date-time", "description": "Added 2026-09-12, on EVERY data frame of the native WebSocket and the push feed (score, point, point_update, status, the signal family): the UTC instant (ms) the frame left our process for the socket or the fan-out sidecar — the third clock next to the state's `timestamp` (arbiter commit) and a point's `ts` (capture)." }, "match_id": { "type": "integer" }, "point": { "$ref": "#/components/schemas/LivePoint" }, "pbp_coverage": { "type": "string", "enum": [ "point", "game" ] }, "quality": { "type": "string", "enum": [ "clean", "revised" ] } } }, "Tournament": { "type": "object", "description": "One tournament of the catalogue — the stable id space `Match.tournament_id` joins, one row per tournament × event type, stable across seasons.", "properties": { "id": { "type": "string", "description": "The stable id `Match.tournament_id` joins." }, "name": { "type": [ "string", "null" ] }, "tour": { "type": [ "string", "null" ], "enum": [ "atp", "wta", "challenger", "itf", "juniors", null ] }, "surface": { "type": [ "string", "null" ], "enum": [ "hard", "clay", "grass", null ], "description": "Court surface, null where the catalogue holds none — 61 of 10,287 tournaments on 2026-09-20. 35 of those are team competitions (Davis Cup, Billie Jean King Cup, Laver Cup), which have no tournament-level surface to hold: each tie is played on the host nation's choice, and that surface is published on each MATCH of the tie instead. The upstream field for those rows carries the DRAW TIER rather than a surface (\"- Preliminary\", \"- Play Offs\", \"- Promotion\"), and a value that is not one of hard/clay/grass is rejected rather than published. 3 are the exhibition catch-all and 23 are ordinary events the upstream catalogue simply never stated a surface for." }, "indoor": { "type": "boolean" }, "city": { "type": [ "string", "null" ], "description": "Host city, from a curated table — null where not curated." }, "country": { "type": [ "string", "null" ], "description": "Host country, ISO-3166 alpha-2 — null where not curated. (NOTE this differs from `player.country` and the `?country=` filter, which use IOC-style lowercase 3-letter codes.)" }, "category": { "type": [ "string", "null" ], "enum": [ "grand_slam", "masters_1000", "tour_finals", "atp_500", "atp_250", "wta_1000", "wta_500", "wta_250", "wta_125", "challenger", "itf", "juniors", null ], "description": "Tournament category where our catalogues agree unambiguously on an exact-name join — null otherwise, never derived from the name. Unchanged by `tier` (2026-09-22) and remains the coarse class; read `tier` for the level." }, "tier": { "type": [ "string", "null" ], "enum": [ "grand_slam", "atp_finals", "atp_1000", "atp_500", "atp_250", "next_gen_finals", "united_cup", "davis_cup", "olympics", "laver_cup", "wta_finals", "wta_elite_trophy", "wta_1000", "wta_500", "wta_250", "wta_125", "bjk_cup", "challenger_175", "challenger_125", "challenger_100", "challenger_75", "challenger_50", "itf_m15", "itf_m25", "itf_w15", "itf_w25", "itf_w35", "itf_w40", "itf_w50", "itf_w60", "itf_w75", "itf_w80", "itf_w100", "juniors", "utr", "exhibition", null ], "description": "The level this tournament is played at in the CURRENT season (added 2026-09-22) — the same closed vocabulary as `tier` on a match (`grand_slam`, `atp_1000` … `atp_250`, `wta_1000` … `wta_125`, `challenger_175` … `challenger_50`, `itf_m15` / `itf_m25`, `itf_w15` … `itf_w100`, the team events, `juniors`, `utr`, `exhibition`). A catalogue row has no season of its own; a match does: the tier is PER SEASON and it moves under one id — Dallas was `atp_250` in 2023 and 2024 and `atp_500` from 2025; Estoril `atp_250`, then `challenger_175` in 2025, then `atp_250` again in 2026; Eastbourne `wta_500` through 2024 and `wta_250` from 2025 — so read the tier off each MATCH for its season, never copy this value onto a match. Null when this season's calendar does not list the event — never guessed." }, "tier_source": { "type": [ "string", "null" ], "enum": [ "calendar", "name", "wikipedia", "resolver", null ], "description": "How `tier` was established (added 2026-09-22): `calendar` = the official per-season tour calendar named the level (ATP tour and Challenger calendars, the WTA tournament list); `name` = an unambiguous name rule (the ITF category is in the event's official name — `M25 …`, `W35 …` — team and UTR events are named as such, and the Slam junior draws and exhibitions are their own event type); `wikipedia` = the season's schedule page, used only where the official calendar could not state the level for that season (Eastbourne 2023–2025); `resolver` = resolved after the seed dataset, by the same rules, from the event's name, tour and dates in that season. Null exactly when `tier` is null." } } }, "ArchiveMatch": { "type": "object", "description": "One result of the results archive (1968–2022). Winner/loser-shaped — results data is recorded that way at the source, so the winner is a field, never an inference. Its own id space; `source_id` is the stable corpus key. A result played 2013–2022 may additionally carry a reconstructed point-by-point tape (`ArchiveTape`); results from 1968–2012 have none and never will.", "properties": { "id": { "type": "integer" }, "source_id": { "type": "string" }, "tour": { "type": "string", "enum": [ "atp", "wta" ] }, "level": { "type": [ "string", "null" ], "description": "Source tier code (G/M/A/F/D/C/O, or a futures category code as published)." }, "tournament": { "type": [ "string", "null" ] }, "surface": { "type": [ "string", "null" ] }, "draw_size": { "type": [ "integer", "null" ] }, "event_date": { "type": [ "string", "null" ], "format": "date", "description": "Tournament START date — per-match dates do not exist in this era's records, and we do not invent them." }, "round": { "type": [ "string", "null" ] }, "best_of": { "type": [ "integer", "null" ] }, "minutes": { "type": [ "integer", "null" ] }, "winner": { "$ref": "#/components/schemas/ArchivePlayer" }, "loser": { "$ref": "#/components/schemas/ArchivePlayer" }, "score": { "type": [ "string", "null" ], "description": "The final score as published, e.g. \"6-4 7-6(5)\", \"6-3 RET\", \"W/O\"." }, "outcome": { "type": [ "string", "null" ], "enum": [ "completed", "retired", "walkover", "default", "abandoned", null ], "description": "Parsed from the score's own vocabulary; null when unparseable — never guessed." }, "stats": { "type": [ "object", "null" ], "description": "Detail endpoint only. {\"winner\":{...}, \"loser\":{...}} with aces, double_faults, serve_points, first_in, first_won, second_won, serve_games, bp_saved, bp_faced where the source recorded them; null otherwise (most rows before 1991) — never synthesised." } } }, "ArchivePlayer": { "type": "object", "description": "One participant of an archive result, as the corpus records them.", "properties": { "name": { "type": [ "string", "null" ] }, "hand": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "3-letter code, same vocabulary as `player.country`." }, "rank": { "type": [ "integer", "null" ], "description": "The player's rank AT THE TIME of the match, as published." }, "seed": { "type": [ "integer", "null" ] }, "player_id": { "type": [ "integer", "null" ], "description": "The corpus person id — joins `/history/archive/players` within the same tour. NOT a roster player id." }, "height_cm": { "type": [ "integer", "null" ] }, "age": { "type": [ "number", "null" ], "description": "Age at the time of the match, as the corpus records it." }, "entry": { "type": [ "string", "null" ], "description": "Draw entry where recorded (WC, Q, LL, PR, SE, ...) — null for direct acceptances." } } }, "ArchivePlayerBio": { "type": "object", "description": "One archive person — own id space (the corpus person id that archive match rows carry as `winner.player_id` / `loser.player_id`, scoped per tour), never a roster id. Career-high is computed offline from the corpus's own weekly ranking tables at ingest, never modelled. Null fields are the era's silence.", "properties": { "id": { "type": "integer" }, "tour": { "type": "string", "enum": [ "atp", "wta" ] }, "name": { "type": [ "string", "null" ] }, "hand": { "type": [ "string", "null" ] }, "dob": { "type": [ "string", "null" ], "format": "date" }, "country": { "type": [ "string", "null" ] }, "height_cm": { "type": [ "integer", "null" ] }, "career_high_rank": { "type": [ "integer", "null" ] }, "career_high_date": { "type": [ "string", "null" ], "format": "date", "description": "The earliest week the career-high rank was reached." } } }, "ArchiveCareer": { "type": "object", "description": "Career aggregates over the results archive (1968–2022) — sums and ratios of sums only, nothing modelled. Serve stats exist in the corpus from 1991; `serve.matches_with_stats` states the coverage.", "properties": { "player": { "type": "object", "properties": { "name": { "type": "string" } } }, "span": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] } } }, "record": { "type": "object", "properties": { "wins": { "type": "integer" }, "losses": { "type": "integer" }, "titles": { "type": "integer", "description": "Finals won (excluding abandoned finals)." }, "by_surface": { "type": "object", "additionalProperties": { "type": "object", "properties": { "wins": { "type": "integer" }, "losses": { "type": "integer" } } } }, "by_level": { "type": "object", "additionalProperties": { "type": "object", "properties": { "wins": { "type": "integer" }, "losses": { "type": "integer" } } } } } }, "by_year": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "wins": { "type": "integer" }, "losses": { "type": "integer" } } } }, "serve": { "type": "object", "description": "Summed serve statistics + derived ratios; null ratios where the denominator is zero.", "properties": { "matches_with_stats": { "type": "integer" }, "aces": { "type": "integer" }, "double_faults": { "type": "integer" }, "serve_points": { "type": "integer" }, "first_in": { "type": "integer" }, "first_won": { "type": "integer" }, "second_won": { "type": "integer" }, "serve_games": { "type": "integer" }, "bp_saved": { "type": "integer" }, "bp_faced": { "type": "integer" }, "first_in_pct": { "type": [ "number", "null" ] }, "first_won_pct": { "type": [ "number", "null" ] }, "second_won_pct": { "type": [ "number", "null" ] }, "bp_saved_pct": { "type": [ "number", "null" ] }, "aces_per_match": { "type": [ "number", "null" ] } } } } }, "ArchiveTape": { "type": "object", "description": "The reconstructed 2013-2022 point-by-point tape for one archive result. Same envelope as HistoryTape so one parser reads both halves of the tape product, with the differences that are TRUE: `match` is the archive result row (winner/loser-shaped), `profiles` is always empty, and every row carries a null `timestamp`, a null `age_seconds` and null model fields because nobody watched these matches and no model scored them. `meta` has no `match_id` — an archive id is not a match id.", "properties": { "match": { "$ref": "#/components/schemas/ArchiveMatch" }, "tape": { "type": "array", "description": "The score sequence in seq order, WINNER-FIRST (`sets[0]` / `games[0]` / `points[0]` are the winner's, and a `server` of 1 means the winner was serving) — see HistoryTapeRow. `point_winner` and `winner` (since 2026-09-22) are present; on a per-GAME tape, where consecutive rows differ by a whole game, each reads the side whose game count rose (the game point was theirs) and says nothing about the other points of that game.", "items": { "$ref": "#/components/schemas/HistoryTapeRow" } }, "tiebreaks": { "type": [ "array", "null" ], "description": "Per-set tiebreak final scores, same rule and shape as on HistoryTape. Usually PRESENT even on a per-game tape — the pre-2023 record expands points inside tiebreaks even where it does not elsewhere.", "items": { "type": [ "object", "null" ], "properties": { "p1": { "type": "integer" }, "p2": { "type": "integer" } } } }, "profiles": { "type": "array", "description": "Always empty. The key is kept so the envelope matches HistoryTape; no model analysis exists, or could exist, for a pre-2023 match.", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "archive_match_id": { "type": "integer", "description": "The `archive_matches.id` this tape belongs to. Named in full because it is NOT a match id — passing it to a `/matches/...` route resolves a different, real record without erroring." }, "tiebreaks_source": { "type": [ "array", "null" ], "description": "Aligned to `tiebreaks`, same contract as on HistoryTape. Every populated entry here reads `reconstruction` — the archive tape IS the reconstruction and nothing else is consulted.", "items": { "type": [ "string", "null" ] } }, "rows": { "type": "integer", "description": "Rows returned. Read next to `granularity` before comparing it with a 2023+ tape's row count. Across the corpus a tape averages 146 rows (median 138, range 4-570); a per-game tape carries one row per game and is far shorter than a point tape of the same match." }, "coverage": { "type": "string", "enum": [ "reconstructed", "reconstructed_partial" ], "description": "`reconstructed` (96.3% of the corpus) = the tape reproduces the published final score exactly, and that score is a match that finished. `reconstructed_partial` (3.7%) HAS TWO CAUSES and the label does not say which: either the match itself stopped early (a retirement or abandonment prefix), OR the tape is per-GAME — every one of the 556 game-granular tapes carries this label however complete it is, because the coverage vocabulary is closed and `game` has no word of its own. It therefore does NOT on its own mean incomplete match coverage: read `granularity` and the match's own score/outcome for that. Never `from_start` or `partial`: both assert we watched the match, and nobody watched these. On the 2023+ tape the same word means only short-at-either-end." }, "granularity": { "type": "string", "enum": [ "point", "game" ], "description": "What one row resolves to. `point` = the record advances within a game — 99.4% of the corpus (97,293 matches). `game` = one row per game, with points expanded only inside tiebreaks — 556 matches, 555 of them in 2013 and one in 2014; every season from 2015 on is 100% point-granular. `point_winner` / `winner` on a per-game tape read the side whose game count rose on each row, and nothing about the game's other points. Orthogonal to `coverage` as an axis, though a `game` tape is always labelled `reconstructed_partial`." }, "point_source": { "type": "string", "enum": [ "reconstructed" ], "description": "Always `reconstructed`. It is a property of the dataset, not a measurement of these rows, and there is no other value it can take." }, "model_rows": { "type": "integer", "description": "Always 0 — no model output exists for a pre-2023 match. Present so a client parsing both halves of the tape product reads one shape." }, "observed_rows": { "type": "integer", "description": "Always 0 — no row here was watched live." }, "point_source_detail": { "type": "string", "description": "Always `reconstruction from public record`. Stated in the payload so the provenance travels with the data rather than living only in a customer's memory of these docs." }, "sequence": { "type": "string", "enum": [ "raw" ], "description": "Always `raw`. There is nothing to collapse — a reconstructed tape has one source and no corrections, so `?sequence=clean` has no meaning here; the parameter is ignored, not refused." }, "generated_at": { "type": "string", "format": "date-time" } } } } }, "HeadToHead": { "type": "object", "description": "The record between two players across both halves of the product — the results archive (1968–2022) and our own completed matches (2023→now). Totals count meetings with a KNOWN winner; `undecided` counts the rest.", "properties": { "players": { "type": [ "object", "null" ], "description": "The resolved names ({\"p1\":{\"name\"}, \"p2\":{\"name\"}}); null when no player matches the fragments." }, "totals": { "type": "object", "properties": { "p1_wins": { "type": "integer" }, "p2_wins": { "type": "integer" }, "meetings": { "type": "integer" }, "undecided": { "type": "integer", "description": "Meetings with no derivable winner (never counted in wins)." } } }, "by_surface": { "type": "object", "description": "Per-surface win split of the decided meetings; keys are surface names plus 'unknown'.", "additionalProperties": { "type": "object", "properties": { "p1": { "type": "integer" }, "p2": { "type": "integer" } } } }, "meetings": { "type": "array", "description": "Newest first, capped at 200. `era` says which half served the row — 'archive' rows carry `archive_match_id`/`level`/`score`; 'current' rows carry `match_id`/`round_code` and read their score from the match endpoints. `winner` is 1|2 OF THIS H2H (p1/p2 as requested), null when underivable.", "items": { "type": "object", "properties": { "era": { "type": "string", "enum": [ "archive", "current" ] }, "date": { "type": [ "string", "null" ] }, "tournament": { "type": [ "string", "null" ] }, "level": { "type": [ "string", "null" ] }, "round": { "type": [ "string", "null" ] }, "surface": { "type": [ "string", "null" ] }, "score": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "winner": { "type": [ "integer", "null" ] } } } }, "stats": { "type": [ "object", "null" ], "description": "ULTRA only — per-player serve/return/break-point aggregates over the pairing, keyed `p1`/`p2`. Each side carries `archive_serve` (serve-side figures, meetings from 1991) and `current` (2023+, adding return and break-point conversion, aces and winners), each with its own `meetings_with_stats` sample size. Absent below ULTRA." } } }, "RallyMatch": { "type": "object", "description": "One charted match of the rally-construction corpus — its own id space, keyed on `rally_match_id`.", "properties": { "rally_match_id": { "type": "integer", "description": "The id this product is keyed on." }, "source_id": { "type": "string" }, "match_id": { "type": [ "integer", "null" ], "description": "OUR match id, when the charted match is also one we hold. Null otherwise — most charted matches predate our own collection." }, "date": { "type": [ "string", "null" ], "format": "date" }, "tournament": { "type": [ "string", "null" ] }, "round": { "type": [ "string", "null" ] }, "surface": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ], "enum": [ "M", "W", null ] }, "best_of": { "type": [ "integer", "null" ] }, "players": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "hand": { "type": [ "string", "null" ], "enum": [ "R", "L", "U", "A", null ] } } } }, "points": { "type": "integer", "description": "Charted points in this match." }, "points_parsed": { "type": "integer", "description": "How many of them our parser read cleanly — the per-match quality number." } } }, "RallyPoint": { "type": "object", "description": "One charted point. `raw` is the charter's own string, verbatim, and is ALWAYS present; the parsed fields are our reading of it. `parsed` is false when the notation contained something we could not read cleanly — the recognised part is still returned. A consumer who wants only unambiguous rows filters on `parsed`.", "properties": { "point": { "type": "integer" }, "set": { "type": "array", "items": { "type": [ "integer", "null" ] }, "maxItems": 2 }, "games": { "type": "array", "items": { "type": [ "integer", "null" ] }, "maxItems": 2 }, "score": { "type": [ "string", "null" ], "description": "e.g. '30-40'." }, "game": { "type": [ "integer", "null" ] }, "is_tiebreak": { "type": "boolean" }, "server": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "point_winner": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "raw": { "type": [ "string", "null" ], "description": "The charter's shot string; both serves joined by ';' when the first was a fault." }, "parsed": { "type": "boolean" }, "serve_number": { "type": [ "integer", "null" ], "enum": [ 1, 2, null ] }, "serve_direction": { "type": [ "string", "null" ], "enum": [ "wide", "body", "down_the_t", null ] }, "rally_length": { "type": [ "integer", "null" ], "description": "Strokes including the serve. An ace is 1, a double fault 0." }, "outcome": { "type": [ "string", "null" ], "enum": [ "winner", "forced_error", "unforced_error", "error", "other", null ], "description": "`error` = the charter recorded a miss without saying whether it was forced. Never guessed." }, "error_location": { "type": [ "string", "null" ], "enum": [ "net", "wide", "deep", "wide_and_deep", null ] }, "ending_stroke": { "type": [ "string", "null" ] }, "ending_wing": { "type": [ "string", "null" ] }, "is_ace": { "type": "boolean" }, "is_double_fault": { "type": "boolean" }, "is_serve_and_volley": { "type": "boolean" }, "is_unreturned": { "type": "boolean", "description": "Derived (added 2026-09-05). The server won the point without the returner putting the ball in play. A double fault is never unreturned." }, "unreturned_kind": { "type": [ "string", "null" ], "enum": [ "ace", "serve_winner", "serve_forced_error", "return_forced_error", "return_unforced_error", "return_error", null ], "description": "How the serve went unreturned. `serve_winner` is a serve winner charted without a direction code (so `is_ace` is unset) — count it with the aces. `return_error` = the return missed and the charter did not say whether it was forced. Null when the return was in play or the parse could not say." }, "shots": { "type": "array", "items": { "$ref": "#/components/schemas/RallyShot" } } } }, "RallyShot": { "type": "object", "description": "One stroke. Shots are numbered from the serve: serve 1, return 2, the server's next ball 3.", "properties": { "number": { "type": "integer" }, "code": { "type": "string", "description": "The charter's raw code, e.g. 'f'." }, "stroke": { "type": [ "string", "null" ], "enum": [ "serve", "groundstroke", "slice", "volley", "half_volley", "swinging_volley", "overhead", "drop_shot", "lob", "trick", "unknown", null ] }, "wing": { "type": [ "string", "null" ], "enum": [ "forehand", "backhand", null ], "description": "The side it was struck FROM." }, "direction": { "type": [ "string", "null" ], "enum": [ "forehand_side", "middle", "backhand_side", null ], "description": "Where the ball was sent." }, "depth": { "type": [ "string", "null" ], "enum": [ "shallow", "mid", "deep", null ] }, "position": { "type": [ "string", "null" ], "enum": [ "approaching", "at_net", "baseline", null ] } } } } } }