openapi.yaml

openapi: 3.1.0
info:
  title: Live Tennis API
  version: "1.7.1"
  contact:
    name: Live Tennis API
    url: https://livetennisapi.com
  license:
    name: MIT
    url: https://github.com/livetennisapi/openapi/blob/main/LICENSE
  termsOfService: https://livetennisapi.com/terms
  description: |
    Real-time tennis scores, player data, match-winner market prices, and
    model-driven match analysis. Read-only. Coverage spans ATP, WTA,
    Challenger, ITF and the junior Grand Slam draws — depth differs by tour
    and surface; `GET /history/coverage` states the measured numbers.

    Access is tiered (FREE / BASIC / PRO / ULTRA). Each tier includes
    everything in the tiers below it; the concrete deltas are:

    `FREE` — self-serve, no card (https://livetennisapi.com/subscribe/free).
    Live and upcoming matches, current scores, players, fixtures, the
    tournament catalogue (`/tournaments`), and your own usage stats.
    30 requests/minute, 100/day. No historical results, no market prices,
    no model fields, no WebSocket.

    `BASIC` — adds historical data: the completed-match listing
    (`/history/matches`, and `status=completed` on `/matches`), the
    per-match point-by-point tape with the model win-probability on the
    rows where the model ran
    (`/history/matches/{matchId}`), the measured completeness rollup
    (`/history/coverage`), and the results archive (1968–2022) —
    deep results (`/history/archive/matches`), archive player bios
    (`/history/archive/players`), career aggregates
    (`/history/archive/career`) and head-to-head (`/h2h`).
    60 requests/minute, 1,000/day.

    `PRO` — adds match events (`/matches/{matchId}/events`), market prices
    (`/markets`, `/markets/{matchId}/prices`, `/matches/{matchId}/prices`),
    the pre-built monthly bulk history packages (`/history/packages`) and the
    rank-ordered rankings listing (`/rankings?system=`).
    300 requests/minute, 10,000/day.

    `ULTRA` — adds model analysis (`/matches/{matchId}/analysis`), the live
    model fields (`win_probability_p1`, `danger`) on every score object,
    in-play match statistics (`/matches/{matchId}/statistics`), per-player
    as-of ranking records (`/rankings?player=`), the as-of Elo tape
    (`/rankings?system=elo` — both modes, plus `kind=elo` bulk packages),
    rally construction
    (`/rally/matches`, shot-by-shot charted data), career and per-match
    charting stats (`/charting/players`, `/charting/matches/{chartingMatchId}`),
    the WebSocket live feed at `/ws` and the high-fan-out push feed
    (`/ws-token`), and outbound webhooks (direct keys). 600 requests/minute,
    500,000/day.

    History runs in two continuous halves, deliberately non-overlapping: the
    point-by-point tape (2023→now) covers January 2023 to now, match by
    match, point by point; the results archive (1968–2022) covers 1968
    through 2022 as winner/loser-shaped RESULTS (final score, seeds, ranks at
    the time — no point-by-point). The archive ends exactly where the tape
    begins, so no match is ever served from two datasets.

    A call above your tier returns `403 {"error":"upgrade_required"}` — never
    a silent empty result.

    CORS is enabled across the REST surface: every response carries
    `Access-Control-Allow-Origin: *` (GET/OPTIONS, no credentials mode — there
    is no cookie or session, and a wildcard origin is incompatible with
    credentials by design). Putting a FREE key in browser code is acceptable —
    it is capped and revocable; a paid key belongs server-side only.

    The `/history/*` endpoints are also sold standalone as the **Historical
    Data API** (no live-API subscription required): **Starter** — single-match
    point-by-point tape reads via the API (tape plus the model win-probability
    per point), all tours (ATP/WTA/Challenger/ITF/juniors), one match per
    request, no bulk downloads; **Pro** — everything in Starter plus bulk
    monthly package
    downloads and higher rate limits; **Business** — everything in Pro plus
    year-scale archive exports, top rate limits and priority support. One-off
    1-month and 1-year access passes are available without a subscription.
    The results archive (1968–2022) endpoints (`/history/archive/*`, `/h2h`)
    ride with the same entitlement — any active History plan, Starter
    included, opens them alongside the tape endpoints.
    Plans and prices: https://livetennisapi.com/historical-tennis-data-api

    All timestamps are UTC ISO 8601 with a `Z` suffix. List endpoints return
    `{data, meta}`; single resources return the object directly. Ignore
    unknown fields — additive changes land within v1.

    A native WebSocket live feed (ULTRA) exists at `/ws` under the same base
    URL. Subscribe with one JSON frame whose keys are `topics` and
    (optionally) `signals`: `{"topics":["live-scores"]}` — `topics` may also
    name `"match:<id>"`. The server acks with a `subscribed` frame, then
    pushes `score` frames on every change plus a `ping` heartbeat roughly
    every 15s. Score frames carry the ULTRA model fields
    (`win_probability_p1`, `danger`) live; a null there means the model had
    no output for that point, not that the field is REST-only. Opt into extra
    signals with `{"topics":["live-scores"],"signals":["break_point"]}` to
    also receive `break_point` and `break_point_result` frames (schemas
    `BreakPoint` / `BreakPointResult`). Without `signals`, score frames only.

    `signals` may also name `points` — the live per-point event stream: one
    `point` frame (schema `PointFrame`) per persisted point of your
    subscribed matches, ordered per match by `seq`. The signal is
    config-gated and ships OFF by default; the `subscribed` ack echoes the
    signals actually active, so `points` present in the ack means point
    frames will flow and missing means they will not. Frames arrive only for
    matches with `pbp_coverage: "point"` — a `game`-coverage match sends
    none, honestly. Best-effort with NO replay: on reconnect (or to join
    mid-match) catch up via `GET /matches/{matchId}/points?after_seq=` and
    dedup by `seq`.

    Max 2 concurrent connections per key. For high fan-out, `GET /ws-token`
    mints a token for the separate push feed.

    Getting a match id: it is the `id` field on any match object returned by
    `GET /matches`, `GET /fixtures` or `GET /history/matches`, and the same value
    works on every route that takes `matchId`.

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`) and returns `403 upgrade_required` on a FREE key.
        The `player`, `country`, `from`/`to`, `tour` and `draw` 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.
      operationId: listMatches
      parameters:
        - name: status
          in: query
          description: >-
            `live` (default) and `upcoming` are FREE; `completed` requires
            BASIC — paging completed results is the history surface.
          schema: { type: string, enum: [live, upcoming, completed], default: live }
        - $ref: "#/components/parameters/tour"
        - $ref: "#/components/parameters/draw"
        - $ref: "#/components/parameters/player"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/playedFrom"
        - $ref: "#/components/parameters/playedTo"
        - $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" }
        "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`.
      operationId: getMatchScore
      parameters: [ { $ref: "#/components/parameters/matchId" } ]
      responses:
        "200":
          description: Current score (ULTRA adds win_probability_p1 + danger)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Score" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "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" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/analysis:
    get:
      summary: Model analysis for a match (ULTRA)
      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": { $ref: "#/components/responses/NotFound" }
        "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.


        DERIVED (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.


        MEASURED (`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.


        Measured 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).


        `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.


        THE 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.


        Tiebreak 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" }
        "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.


        READ 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 this match has a true per-point stream;
        `"game"` means only the snapshot score path covers it — `points` is
        empty and that is an answer, not an error. 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).


        Each 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.


        Up 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.


        COMPLETED MATCHES: live capture is inherently partial — the stream
        serves what arrived while the match ran, and the match-closing point
        never streams live. Where a measured-complete recorded point sequence
        of the finished match exists, this endpoint serves 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 — every live match, and any completed match
        without a measured-complete recorded sequence) or `reconstruction`
        (the projected complete sequence; `quality` is `clean`, every
        transition measured legal). Completeness beats the partial live
        capture 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: after a match completes and flips to
        `reconstruction`, re-read from `after_seq=0` rather than resuming a
        live cursor into it.
      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`.
      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" }
        "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)
      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": { $ref: "#/components/responses/NotFound" }
        "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.
      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"
        - $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: Match-winner market(s) for a match (PRO)
      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)
      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": { $ref: "#/components/responses/NotFound" }
        "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. 404 when the match has no mapped market.
      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 }
      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; raise limit or narrow
                          minutes.
                      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" }
        "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).
        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.
      operationId: listCompletedMatches
      parameters:
        - $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"
        - 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=`.
      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).
        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.


        The 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.


        WORKS 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 — 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.
            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` 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" }
        "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).


        A 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.
      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/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: 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 (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. 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], 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). 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`), 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], default: tape }
          description: >-
            Package family; `rankings`, `rally` and `elo` require ULTRA or a History Pro/Business subscription (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.
        - name: format
          in: query
          required: false
          description: Omit for the JSON manifest; set to download the file.
          schema: { type: string, enum: [jsonl, csv] }
      responses:
        "200":
          description: >-
            The manifest (no `format`), or the bulk file as an attachment
            (`format=jsonl` streams NDJSON, `format=csv` streams 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/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.


        TWO 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).


        SYSTEM=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.


        SYSTEM=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.
        - 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.
        - 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`.
        - 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`.
        - 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]
          explode: true
          description: >-
            Restrict to one or more systems. Omit for all of the official
            systems — `elo` is NEVER included implicitly and must be named,
            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.


        It 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" }
        "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. Every field
        is a raw SUM over the player's Total rows and `matches_charted` states
        the sample. COVERAGE IS CURATED — 11,646 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.


        Each delivery carries `X-LTAPI-Signature` (`sha256=<hex>` — 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`).


        Delivery 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] }
                  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" }
  /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.


        The 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": "<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": <frame>}}}`; (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.


        The `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). 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`.
      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 <key>"
    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.

        Get it from any match list, where it is the `id` field of each match object:
        `GET /matches?status=live` (in progress), `GET /matches?status=upcoming` or `GET /fixtures` (scheduled), `GET /matches?status=completed` or `GET /history/matches` (finished).

        Ids are stable for the life of a match, so one captured before it starts still resolves after it finishes.
      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.
    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" }
    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:
    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, points_disabled, bad_period,
            bad_year, bad_format, bad_tour, bad_country, ambiguous_name,
            not_charted, not_found, 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.
    Score:
      type: object
      description: ULTRA adds win_probability_p1 + danger.
      properties:
        sets:
          type: array
          items: { type: integer }
        games:
          type: array
          description: "[games_p1, games_p2]; each a per-set list"
          items:
            type: array
            items: { type: integer }
        points:
          type: array
          description: >-
            In-game points as tennis strings ("0", "15", "40", "AD"). Entries
            can be NULL — observed live on completed matches, which also carry
            empty games arrays. Do not decode into non-nullable strings.
          items: { type: [string, "null"] }
        server: { type: [integer, "null"], enum: [1, 2, null] }
        is_tiebreak: { type: boolean }
        win_probability_p1: { type: [number, "null"] }
        danger: { type: [number, "null"] }
        timestamp: { type: [string, "null"], format: date-time }
    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"] }
        ranking_points: { type: [integer, "null"] }
        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"] }
            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 on matches ingested before the catalogue covered their
            tournament. (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.)
        surface: { type: [string, "null"], enum: [hard, clay, grass, null] }
        indoor: { type: boolean }
        format: { type: [string, "null"], enum: [BO3, BO5, 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: >-
            The round in the archive's controlled vocabulary, normalized from
            the free-text label above (`Q` = qualifying round the feed does
            not number). This is the field to branch on; it matches
            `/history/archive/matches?round=` exactly. Null when the label is
            unrecognised — never guessed.
        status: { type: string, enum: [upcoming, live, completed, cancelled] }
        event_status:
          type: [string, "null"]
          enum: [Retired, Cancelled, Walk Over, Postponed, Interrupted, null]
          description: >-
            How the match ended (or paused) when it 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 means the match completed normally OR the
            outcome was never resolved — the feed does not distinguish those.
            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 }
        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.
        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.
    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 = p1's outcome, 2 = p2's
        bid: { type: [number, "null"] }
        ask: { type: [number, "null"] }
        mid: { type: [number, "null"] }
        spread: { type: [number, "null"] }
        price_source:
          type: [string, "null"]
          description: Feed category, e.g. prediction_market
        synthetic:
          type: [boolean, "null"]
          description: >-
            true = bid/ask estimated from mid (not a live order book);
            false = real top-of-book; null = unknown (older ticks)
        timestamp: { type: [string, "null"], format: date-time }
    Event:
      type: object
      properties:
        type: { type: string, enum: [break, set_won, game_won, momentum_run] }
        player: { type: [integer, "null"], enum: [1, 2, null] }
        timestamp: { type: [string, "null"], format: date-time }
    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. A null `timestamp` is the reliable row-level
        marker of a reconstructed row; the model fields alone are not, 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.
      properties:
        sets:
          type: array
          items: { type: integer }
        games:
          type: array
          items:
            type: array
            items: { type: integer }
        points:
          type: array
          items: { type: string }
        server: { type: [integer, "null"], enum: [1, 2, null] }
        is_tiebreak: { type: boolean }
        win_probability_p1: { type: [number, "null"] }
        danger: { type: [number, "null"] }
        timestamp: { type: [string, "null"], format: date-time }
        point_winner:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            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.
    HistoryTape:
      type: object
      description: >-
        The full per-match history tape (BASIC, or Historical Data API
        Starter+). `tape` rows INCLUDE the model fields `win_probability_p1`
        and `danger` per point — on this product they are part of the tape
        itself, not an ULTRA upsell.
      properties:
        match:
          $ref: "#/components/schemas/Match"
          description: Match metadata with the final score embedded.
        tape:
          type: array
          description: Chronological score sequence — see HistoryTapeRow.
          items: { $ref: "#/components/schemas/HistoryTapeRow" }
        tiebreaks:
          type: [array, "null"]
          description: >-
            Per-set tiebreak final scores from OBSERVED states only, aligned
            to the sets of the final scoreline: `{"p1", "p2"}` for a 7-6 set
            whose observed maximum tiebreak state is a valid terminal shape
            (max >= 7, margin >= 2), null per set otherwise — a breaker whose
            closing point the feed skipped reads null rather than an
            under-report. Null when the match has no 7-6 set. Present on
            `raw` and `clean` alike.
          items:
            type: [object, "null"]
            properties:
              p1: { type: integer }
              p2: { type: integer }
        profiles:
          type: array
          description: Model profiles produced during the match, oldest first.
          items: { $ref: "#/components/schemas/ModelProfile" }
        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: >-
                True when the tape was served from the immutable archive
                rather than the live-score table. Content is identical.
            points:
              $ref: "#/components/schemas/PointsMeta"
            model_rows:
              type: integer
              description: >-
                How many of the RETURNED rows carry a model probability. The
                model stamp is best-effort in the live path, so no coverage
                value implies it — this is the count for THIS response,
                derived per read and never stored.
            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: 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,
            it reaches a finished legal final scoreline (or the match ended
            early — retirement/walkover), and it is not known-truncated.
        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 (rows − 1).
        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.
        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. The nightly ledger's verdict
            on whether a point-complete reconstruction exists for this match:
            true/false when measured, null when not yet measured — never
            guessed.
    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. A month may also list the complete-basis ADDENDUM
        files (tennis_history_points_complete_<period>.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=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` 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 }
        kind:
          type: string
          enum: [tape, rankings, rally, archive, elo]
          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.
    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.
    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. Read
                    from a per-match ledger reconverged nightly. 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). 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"] }
        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.

        EVERY 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:

        TIER 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.

        TIER 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.

        TIER 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.

        A `_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]
        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.
        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.
    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` = this match has a true per-point stream; `game` = only
            the snapshot score path covers it (`points` is empty — an answer,
            not an error).
        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.
        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 (every live match, and any completed match without a
            measured-complete recorded sequence); `reconstruction` = the
            complete recorded point sequence of a finished match, projected
            into point frames at read time — includes the match-closing point,
            `seq` contiguous 1..N, `ts` null on every frame. Completeness
            beats the partial live capture wholesale; the two bases are never
            interleaved.
    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. Ordered per match by `seq`;
        dedup/resume on `seq`. Best-effort, NO replay — catch up via
        `GET /matches/{matchId}/points?after_seq=`.
      properties:
        type: { type: string, const: point }
        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] }
        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.
    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.
      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"] }
    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 }
        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]