openapi.yaml

openapi: 3.1.0
info:
  title: Live Tennis API
  version: "1.13.60"
  contact:
    name: Live Tennis API
    url: https://livetennisapi.com
  license:
    name: MIT
    url: https://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 market prices, no model fields, no
    WebSocket. Historical results are not part of the tier, but a FREE key
    may spend 20 calls per calendar month on the history endpoints as a
    taste of the product — served exactly like an entitled call. Past that
    they answer `403 upgrade_required` carrying
    `free_history_taste: "used"`.

    `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 reconstructed 2013–2022 archive tape
    (`/history/archive/matches/{archiveId}/tape` — also opened by ANY active
    History plan, Starter included), 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.

    Archive results played **2013–2022** additionally carry a RECONSTRUCTED
    point-by-point tape at `/history/archive/matches/{archiveId}/tape` — the
    score sequence behind the published result, rebuilt from the public record
    after the fact. 97,901 matches / 14,340,663 rows, seasons **2013–2022
    ONLY**: the archive holds a further 977,903 results from 1968–2012 and NOT
    ONE of them has a tape, because there is no public point-by-point record of
    those years to rebuild and we do not manufacture one. Write the range as
    2013–2022, never as "pre-2023" — the second phrasing reads as 1968 onward
    and is wrong by 45 seasons.

    Nobody watched those matches, and the data says so: `timestamp`,
    `win_probability_p1` and `danger` are null on EVERY row and cannot be
    filled in later — the production table has no timestamp column at all, and
    the promotion script refuses to run if one ever appears.
    Contrast the 2023→now tape, which is our own recording: the rows we
    actually watched carry a real clock, and most of them a model probability.
    Coverage of the era is real but partial — 19.3% of archive matches played
    2013–2022 and 44.9% of tour-level play; main-draw tour buckets run
    91.6–98.7%, ATP Challenger main draws 55.3% and Challenger qualifying
    33.6%, slam QUALIFYING only 16.0% (ATP) / 18.1% (WTA), and ITF/futures
    effectively nothing (25 of 116,575 ATP futures matches). It is not a
    complete record of the era and is not sold as one.

    Two different gates, on purpose: the per-match tape needs core ULTRA **or
    any active History plan, Starter included**; the per-year bulk files
    (`/history/packages?kind=archive_tape`, 2013–2022, JSONL + CSV) need core
    ULTRA **or** a History Pro/Business subscription (an active one-off package
    window counts). Core PRO carries NEITHER — it reads the archive RESULT and
    is refused the tape.

    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, and that includes the
    reconstructed 2013–2022 archive tape. The per-year `archive_tape` bulk
    files do not: those need Pro, Business or an active one-off package pass,
    because a Starter grant reads tapes one at a time and does not download
    years of them.
    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 — and
    `signals:["stoppages"]` (2026-09-12) for the stoppage family: medical
    timeouts, trainer calls, toilet breaks, whole-match stops and clock-inferred
    pauses, each an Event object plus `match_id` — (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. On the live basis `seq` is ARRIVAL order, not match
    order: use it to page, dedup and resume, and sort by
    `(set, game, number)` to replay in playing order — a tuple that may
    repeat or carry a null `number`, so it orders points without identifying
    them (see `GET /matches/{matchId}/points`). 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.

    CLOSE CODES. Every refusal sends its `error` frame **and then closes with a
    code that says what to do next**, so a reconnect loop or a supervisor keyed
    on the close code alone behaves correctly without parsing the frame. The
    close *reason* repeats the frame's `error` string, so `(code, reason)` is a
    complete diagnosis even if the frame was missed.
    `1013` Try Again Later — transient, the request was fine: `connection_limit`
    (reason `connection_limit:per_key` or `connection_limit:server`) and
    `service_unavailable`. Back off and retry; for `per_key` release a
    connection first, or move to the push feed, which has no shared ceiling.
    `1008` Policy Violation — the request as sent will never be accepted:
    `unauthorized`, `upgrade_required`, `email_unverified`, `client_blocked`,
    `bad_json`, `no_topics`, and any mid-stream loss of access. Fix the request
    or the credentials; do not retry unchanged.
    `1012` Service Restart — reconnect with backoff and re-subscribe.
    `1000` Normal Closure — you closed it, or the stream ended normally.
    Changed 2026-09-18: refusals raised during the *handshake* previously closed
    `1000` with an empty reason, indistinguishable from an orderly shutdown, so
    a client awaiting its `subscribed` ack saw only a normal close. The error
    frame was, and still is, delivered before the close; only the close code and
    reason changed.

    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`). A FREE key may spend its 20 free history calls
        per calendar month here; past that the answer is
        `403 upgrade_required` carrying `free_history_taste: "used"`.
        The `player`, `country`, `from`/`to`, `tour`, `draw`, `has_analysis`
        and `has_market` filters are optional, AND-composed, applied inside the
        query (before pagination), and work on every status — omitting them
        returns exactly what the endpoint returned before they existed.
        `has_analysis` and `has_market` are the two availability flags every row
        already carries: filter the slate with them and call
        `/matches/{matchId}/analysis` and `/matches/{matchId}/prices` only for
        the ids that have something, rather than probing per match for a 404.
      operationId: listMatches
      parameters:
        - name: status
          in: query
          description: >-
            `live` (default) and `upcoming` are the FREE current-state picture.
            `completed` and `cancelled` are terminal LISTINGS, part of the
            history product (BASIC, or any History plan on a free key; a
            FREE key's 20 free history calls each month are served here too).
            `cancelled` covers feed-cancelled, walkover-with-no-stated-winner
            and postponed-never-played matches; a walkover that named its
            winner is `completed`. `cancelled` pages with `limit`/`offset`
            (optionally `from`/`to`) and does NOT accept `updated_since`
            (400 `bad_request`). Any other value is a 400 `bad_status`
            carrying the accepted list in `allowed`.
          schema: { type: string, enum: [live, upcoming, completed, cancelled], default: live }
        - $ref: "#/components/parameters/tour"
        - $ref: "#/components/parameters/draw"
        - $ref: "#/components/parameters/player"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/tournamentId"
        - $ref: "#/components/parameters/tier"
        - $ref: "#/components/parameters/hasAnalysis"
        - $ref: "#/components/parameters/hasMarket"
        - $ref: "#/components/parameters/isQualifying"
        - $ref: "#/components/parameters/gender"
        - $ref: "#/components/parameters/playedFrom"
        - $ref: "#/components/parameters/playedTo"
        - $ref: "#/components/parameters/updatedSince"
        - $ref: "#/components/parameters/withdrawnSince"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Matches with latest score
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Match" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}:
    get:
      summary: Full match detail (FREE; +market PRO, +analysis ULTRA)
      operationId: getMatch
      parameters: [ { $ref: "#/components/parameters/matchId" } ]
      responses:
        "200":
          description: Match with score; `market` embed at PRO+, `analysis` embed at ULTRA
          content:
            application/json:
              schema: { $ref: "#/components/schemas/MatchDetail" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/score:
    get:
      summary: Current score only — lowest-latency REST read (FREE)
      description: >-
        This is a POINT-IN-TIME SNAPSHOT: the single current state, overwritten
        on every score commit. It carries no history and no accumulated
        statistics.
        For the SEQUENCE of states — who served each game, hold/break, every
        score state in forward order — use
        `/history/matches/{matchId}?sequence=clean`, which works on a LIVE
        match, not only a completed one. For in-play statistics use
        `/matches/{matchId}/statistics` (ULTRA); they are deliberately not on
        this object, because they can be further behind the match than the
        score and must carry their own `as_of`.
        ARCHIVED FINALS (since 2026-09-20). The live-score rows behind this
        read are retired by a 90-day retention sweep, and a match recovered
        from an official day list may never have had one. When there is no
        live row at all, a SETTLED match — `outcome` non-null on the match
        object: completed, retired, walkover, default, abandoned, unresolved —
        is answered from its archived final: the same read
        `GET /matches?status=completed` already embeds, through the same
        serializer, so the listing and this endpoint can never disagree about
        whether a score exists. A live tape always outranks the archive — the
        fallback is reached only when no publishable live row exists, so a
        live match reads exactly what it did before. An archived final carries
        `age_seconds: null`, `observed_age_seconds: null`, `sources_count:
        null` and `accepted_at: null` — no clock is claimed for a state nobody
        watched — and `timestamp` is null where the archived row has none
        (a reconstructed final). The Score object carries no data-source
        label; whether that final was observed or reconstructed is what
        `GET /history/matches/{matchId}` reports once, in `meta.point_source`.
        404 is kept for: an upcoming match with no row (nothing to serve
        yet), a cancelled match that was never played (nothing settled), and a
        settled match with nothing recorded anywhere — the fallback serves a
        final that exists, it never invents one.
        WITHDRAWN STATES (since 2026-09-23). When the legality gate behind this
        read refuses a state a stream has already published, the `verdict`
        object on the score says so: `kind`, `superseded_sequence`, `reason`
        and `safe_to_resume`. It is null on an ordinary read. The push feed,
        the WebSocket and webhooks carry the same judgement as a
        `score_withdrawn` frame naming the same sequence, so a stream consumer
        learns a state was taken back without polling. `GET /history/incidents`
        is the published register of data-quality incidents.
        THE RECOVERY PATH (since 2026-09-25). A consumer that missed the frame
        cannot get the live `verdict` back, because it is recomputed over the
        newest state and returns null as soon as the next state is accepted.
        Every withdrawal is now recorded durably when the judgement is made:
        pass `?sequence=N` here to have `verdict` answer for the sequence you
        hold, and read `GET /matches/{matchId}/withdrawals` for the whole
        record on a match, including the frame exactly as the feed sent it.
        Before 2026-09-20 every
        settled match older than the retention window answered 404 here
        (13,437 completed matches from the previous 180 days, 157,170 all
        time, measured at the change) while the completed listing served its
        score.
      operationId: getMatchScore
      parameters:
        - $ref: "#/components/parameters/matchId"
        - $ref: "#/components/parameters/sequence"
      responses:
        "200":
          description: >-
            Current score (ULTRA adds win_probability_p1 + danger). On a settled
            match with no live row, the archived final (since 2026-09-20) —
            `age_seconds`, `observed_age_seconds`, `sources_count` and
            `accepted_at` null.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Score" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: >-
            No such match; an upcoming match with no score yet; a cancelled
            match that was never played; or a settled match with nothing
            recorded anywhere — no live row and no archived final. Since
            2026-09-20 a settled match whose live rows were retired by the
            90-day sweep is NOT a 404: it answers 200 with its archived final
            (`age_seconds: null`), the same score `GET /matches?status=completed`
            embeds for it.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/events:
    get:
      summary: Match events, newest first (PRO)
      operationId: listMatchEvents
      parameters:
        - $ref: "#/components/parameters/matchId"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Event" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /events:
    get:
      summary: Slate-wide events feed — every match's events in one call, oldest first, cursor by id (PRO)
      operationId: listSlateEvents
      description: >-
        Added 2026-09-13. The rows of GET /matches/{matchId}/events for EVERY match in
        one request, so a poller watching the whole live slate spends one request per
        tick rather than one per match. `after_id` returns rows with id greater than
        the one passed, ascending, and `meta.next_cursor` names the last id served (null
        on a short page = caught up); `since` (UTC instant) is the first-call lower
        bound; with neither the newest page is served, still ascending. `type` narrows
        to a comma-separated list of event types or the family name `stoppages`
        (stoppage_*, pause_*, medical_timeout_*, trainer_called*, toilet_break_*). Rows
        carry `id` and `match_id` next to the per-match fields. Measured 2026-09-13: a
        scorer-stated stoppage reaches the feed a median 8 s (p90 13 s) after the
        scorer's own instant; the WebSocket `stoppages` signal pushes the same row as it
        is written.
      parameters:
        - name: type
          in: query
          required: false
          schema: { type: string }
          description: Comma-separated event types (see Event.type), or `stoppages` for the whole stoppage family.
          example: medical_timeout_start
        - name: after_id
          in: query
          required: false
          schema: { type: integer }
          description: Serve rows with `id` greater than this, ascending. Take it from `meta.next_cursor` or the last row's `id`.
        - name: since
          in: query
          required: false
          schema: { type: string, format: date-time }
          description: First-call lower bound, a UTC instant. Rows stamped after it, ascending.
          example: "2026-09-13T09:00:00Z"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Events across the slate, ascending id
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/SlateEvent" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "400":
          description: bad_type, bad_after_id or bad_since
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /players/{playerId}/stoppages:
    get:
      summary: One player's in-match stoppages and did-not-finish outcomes, newest first over a window (PRO)
      description: >-
        Added 2026-09-16. Medical timeouts and trainer calls on the player's matches
        (from the stoppage family of GET /matches/{matchId}/events), plus retirements
        and walkovers where THIS player is the non-winner, merged and sorted by `at`
        descending. Window: `since`/`until` (ISO date or UTC instant; default the last
        180 days; at most 366 days, else 400 window_too_long). `kind` filters the seven
        row kinds (default medical_timeout,trainer_called,retirement,walkover); `before`
        pages by `meta.next_cursor`. `meta.latest_medical_timeout` and
        `previous_medical_timeout` are the two newest medical timeouts in the window
        whatever the page or the kind filter. `meta.record_starts` states how far back
        each family goes: stoppage rows exist from 2026-09-12 only; outcome rows from the
        oldest match with a stated winner. In-match stoppages and match outcomes only —
        no off-court injury record exists here. Same PRO capability as /events.
        `GET /players/{playerId}/injuries` serves the identical response.
      operationId: listPlayerStoppages
      parameters:
      - name: playerId
        in: path
        required: true
        schema:
          type: integer
      - name: since
        in: query
        required: false
        schema:
          type: string
        description: Window start — an ISO date (start of that day) or a UTC instant. Default `until` minus 180 days.
        example: '2026-03-19'
      - name: until
        in: query
        required: false
        schema:
          type: string
        description: Window end — an ISO date (the whole of that day) or a UTC instant. Default now.
        example: '2026-09-15T00:00:00Z'
      - name: kind
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated row kinds from medical_timeout, trainer_called, toilet_break, pause, stoppage, retirement, walkover. Default `medical_timeout,trainer_called,retirement,walkover`.
        example: medical_timeout,retirement
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: The `meta.next_cursor` of the previous page (opaque `<kind>:<id>`), valid for the same window and kinds.
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: The player's stoppage and outcome rows, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlayerStoppage'
                  meta:
                    $ref: '#/components/schemas/PlayerStoppagesMeta'
        '400':
          description: window_too_long, bad_window, bad_since, bad_until, bad_kind or bad_cursor
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/UpgradeRequired'
        '404':
          description: >-
            No roster player holds this id. Carries the archive signpost
            (`detail` + `see`) when the id is a corpus person id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PlayerNotFound" }
        '410':
          $ref: '#/components/responses/PlayerGone'
        '429':
          $ref: '#/components/responses/RateLimited'
  /players/{playerId}/injuries:
    get:
      summary: Alias of /players/{playerId}/stoppages — the identical response (PRO)
      description: >-
        Added 2026-09-16. The same handler, parameters, rows and meta as
        /players/{playerId}/stoppages, under the word the request used. The honest name
        is `stoppages`: nothing here is a diagnosis, only what the scorer, umpire or
        result stated.
      operationId: listPlayerInjuries
      parameters:
      - name: playerId
        in: path
        required: true
        schema:
          type: integer
      - name: since
        in: query
        required: false
        schema:
          type: string
      - name: until
        in: query
        required: false
        schema:
          type: string
      - name: kind
        in: query
        required: false
        schema:
          type: string
      - name: before
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Identical to /players/{playerId}/stoppages
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlayerStoppage'
                  meta:
                    $ref: '#/components/schemas/PlayerStoppagesMeta'
        '400':
          description: window_too_long, bad_window, bad_since, bad_until, bad_kind or bad_cursor
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/UpgradeRequired'
        '404':
          description: >-
            No roster player holds this id. Carries the archive signpost
            (`detail` + `see`) when the id is a corpus person id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PlayerNotFound" }
        '410':
          $ref: '#/components/responses/PlayerGone'
        '429':
          $ref: '#/components/responses/RateLimited'
  /matches/{matchId}/status-history:
    get:
      summary: The per-match status ledger — every status / event_status transition with its UTC instant (BASIC, history)
      description: >-
        Added 2026-09-12. Append-only, oldest first: one row per change of `status`
        and/or `event_status`, with the instant we published it, the value before and
        the effective value after, the derived `outcome`, and the newest score row at
        that instant. A correction is a new row, never an edit — a close published as
        `unresolved` and later confirmed shows the flip to `completed`; a completion
        that reopened shows `completed -> live`. `basis: observed` rows exist from
        2026-09-11T22:45:48Z; `basis: backfill` rows (2026-09-12) were reconstructed
        from the one stamp per kind the match row kept before the ledger existed (last
        promotion to live from 2026-09-05, completion instant from 2026-08-21, last
        reopen, last event_status change) — one row per stamp, overwritten intermediate
        transitions are not recovered. A correction to a PUBLISHED result — `status`,
        `event_status`, winner or the final score changing after the match was first
        published as completed — is a new row with `basis: restatement` (from
        2026-09-22), never a silent edit; `result_restated_at` / `result_version` on
        the match summarise them and `GET /history/matches?restated_since=` finds them.
        History capability (BASIC and the Historical
        Data plans), like the tape.
      operationId: getMatchStatusHistory
      parameters:
        - $ref: "#/components/parameters/matchId"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Status transitions, oldest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/StatusChange" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/withdrawals:
    get:
      summary: The durable record of every score state we withdrew on this match (ULTRA)
      description: >-
        Added 2026-09-25. One row per refused `sequence`, oldest first, each
        carrying the `score_withdrawn` frame exactly as the push feed sent it.


        This is the RECOVERY PATH for a missed frame. The `verdict` object on
        `GET /matches/{matchId}/score` is recomputed on every read over the
        newest state, so it returns null again as soon as the next state is
        accepted, which in a live match is seconds. The record here is written
        when the judgement is made, before the frame is delivered, so a
        consumer that was disconnected can still learn that a sequence it holds
        was taken back. `GET /matches?withdrawn_since=` says which matches to
        ask about; `?sequence=N` on the score read answers for one sequence
        without fetching the list.


        ULTRA, the tier that receives the frame on the push feed and the native
        WebSocket. An empty `data` is the ordinary answer and means nothing was
        withdrawn on that match. Records are kept 90 days from the withdrawal.
      operationId: getMatchWithdrawals
      parameters:
        - $ref: "#/components/parameters/matchId"
      responses:
        "200":
          description: Withdrawals on this match, oldest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  match_id: { type: integer }
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/ScoreWithdrawal" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/analysis:
    get:
      summary: Model analysis for a match (ULTRA)
      description: >-
        The model's thesis and profile for one match.


        COVERAGE IS NOT UNIVERSAL, and a polling client should plan for that.
        Analysis is produced per match by the model pipeline rather than
        emitted for every fixture: over the seven days to 2026-08-27, 1,225 of
        2,863 matches that went live or completed carried one (42.8%). A match
        that has none yet returns `404 {"error":"no_analysis"}` (since
        2026-09-02; before that the body was a bare `not_found`) — that is the
        documented absence, not a fault, and it can turn into a 200 later in
        the same match once the pipeline has run. Never treat this 404 as a
        reason to retry harder. The body names which absence it is: `not_found`
        is an id that does not exist; `no_analysis` carries `match_id` and
        `coverage: "none"` for a real match with nothing computed.


        FILTER THE SLATE FIRST. Every row of `GET /matches` and the detail
        carries `has_analysis` (every tier), the same fact this endpoint
        answers 404 about — read it there and call only the matches that carry
        one, instead of spending one 404 per match.


        ONE CALL INSTEAD OF THREE. `GET /matches/{matchId}` carries the same
        thesis and profile in its `analysis` key on ULTRA, alongside `market`
        and `market_price` on PRO and above, next to the live score. It answers
        `200` whether or not analysis and a market exist — the keys are `null`
        instead — so a per-match poll built on the detail route replaces the
        score, analysis and prices calls with one request and never spends a
        call on a 404.
      operationId: getMatchAnalysis
      parameters: [ { $ref: "#/components/parameters/matchId" } ]
      responses:
        "200":
          description: Thesis + profile (either may be null)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Analysis" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404":
          description: >-
            `error: not_found` — no such match id. `error: no_analysis` (with
            `match_id`, `coverage: "none"`, `detail`) — the match exists and
            nothing has been computed for it; `has_analysis` on the match list
            says so without a probe.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/statistics:
    get:
      summary: In-play statistics — aces, double faults, serve split, hold/break %, break points, service & return points (ULTRA)
      description: >-
        In-play statistics for one match, in TWO families that are deliberately
        not merged.


        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" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/points:
    get:
      summary: Live per-point events in seq order — the REST catch-up for the WebSocket point stream (ULTRA)
      description: >-
        The live per-point event stream of one match, in `seq` order. The
        WebSocket `point` frames are best-effort with NO replay, so this
        endpoint is how you join mid-match and how you recover a dropped
        connection: subscribe the WS first, then GET with `after_seq` set to
        the last seq you hold, then dedup everything by `seq` — it is
        per-match, monotonic and never skips a value, so it is the whole
        reconciliation key.


        `seq` IS ARRIVAL ORDER, NOT MATCH ORDER, ON THE LIVE BASIS. It is
        assigned in the order points are committed, and a live match is fed by
        more than one upstream at different speeds, so a point from a set that
        has just ended can be committed AFTER points from the set that follows
        it and carry the higher `seq`. Each row is self-consistent — its `set`,
        `game`, `number`, `score`, `sets` and `games` all describe the point
        that was played — but reading the tape in `seq` order can show the set
        or game counter step backwards. Measured over a recent seven-day
        window this affected a minority of live matches, and never the
        `reconstruction` basis. So `seq` is the right key for paging, dedup and
        resume (unique, stable, strictly increasing — all `after_seq` needs)
        and the wrong key for chronology: sort by `(set, game, number)` to
        replay in playing order. That tuple ORDERS points; it does not
        IDENTIFY them. `number` is null wherever we joined a game already in
        progress, and the same tuple can appear on more than one row — a game
        re-expanded by a second source re-asserts ordinals it already holds,
        which on the live basis is a normal re-statement rather than a
        correction. There is no revision id, superseded-seq or correction
        flag: rows are append-only and never rewritten, so `after_seq` never
        needs a refetch, and the page-level `quality` field reads `revised`
        when the page contains such a re-statement. On the `reconstruction`
        basis of a completed match, `seq` is contiguous 1..N in true match
        order and the two agree.


        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 a per-point stream has DELIVERED for this
        match — at least one played point past the `seq` 1 opener; `"game"`
        means no played point has arrived — only the snapshot score path
        covers it, or the stream holds only its opener so far (a listed match
        that has not started). An answer, not an error; it flips to `point`
        on the first played point. To admit a match as advancing, gate on
        `sequence > 1` (a seeded match is 1) together with `stale: false`. Per-point coverage is
        never promised slate-wide; ITF and qualifying coverage in particular
        is partial. `quality: "revised"` means the upstream feed rewrote an
        already-served prefix at least once during this match; served rows
        are never edited (append-only).


        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: the stored live stream is served on a completed
        match too, whenever it is itself measured complete (the match-closing
        point included) or carries `serve`/`outcome` tags and is legal end to
        end (every transition one attributable point, judged in playing
        order). A projection never carries a clock or a tag, so a complete
        tagged stream is strictly more information than any reconstruction
        of the same match. Only when the stream falls short — no rows at all,
        incomplete and untagged, or a transition nobody can attribute — and a
        measured-complete recorded point sequence of the finished match
        exists does this endpoint serve THAT instead: the complete sequence
        projected into the same point-frame shape, love-love opener through
        the match-closing point, `seq` contiguous 1..N. The response field
        `basis` says which base served the page: `live` (the persisted live
        stream rows) or `reconstruction` (the projected complete sequence;
        `quality` is `clean`, every transition measured legal), and on
        `reconstruction` `basis_reason` says why the stream was not served:
        `stream_absent` (no stored stream rows), `stream_incomplete` (the
        stream is legal but does not measure complete — it joined mid-match
        or stopped short — and carries no tags) or `stream_illegal` (at least
        one transition is not attributable to one point: a gap or a torn
        row). When the reconstruction serves it serves wholesale — the two
        sequences are never interleaved (they share no key, so any merge
        would fabricate an order). On projected frames `ts` is null on every
        row: the recorded sequence carries no per-point clock and we
        fabricate none. `after_seq` pagination and `seq` dedup work
        identically on either basis, but the two bases are different
        sequences: if a completed match reads `reconstruction`, re-read from
        `after_seq=0` rather than resuming a live cursor into it. Precedence
        fixed 2026-09-21: until then a measured-complete recorded sequence
        displaced the stream unconditionally, so a completed match could lose
        its tags the moment a reconstruction landed.


        THE MATCH-CLOSING POINT (added 2026-09-20). Every row is the state
        AFTER a point, so the point that wins a game is carried by the next
        game's `number: 0` opener — and the point that wins the match had no
        next row to be carried by: the live stream never held it, and a
        serve statistic built off the stream was missing every match's last
        point. On a COMPLETED match served on the `live` basis the page now
        closes with ONE terminal row: `seq` = last + 1, `number` 0,
        `sets`/`games` the final score, `score` `{"p1":"0","p2":"0"}`,
        `tiebreak` false, `server` null (nobody serves next), `winner` the
        match winner, `ts` the instant the final score was observed. It is
        built at read time from the stream's last row and the observed final
        score, and only when the two are one point apart — the winner held
        game point and the final is the decided score; nothing is fabricated
        otherwise. `serve`, `outcome` and `tagged_at` on that row are null:
        no source's tag for a match's last point is stored yet. When the
        match ends in a tiebreak (added 2026-09-21) the stream's last row is
        the decisive tiebreak score itself (7-3, 8-6) and the closing row is
        the set roll-up after it: the next game number, `number` 0,
        `tiebreak` false, `sets` incremented for the tiebreak winner, the set
        banked 7-6 in `games`, `score` 0-0, `server` null, the same `winner`
        — the same row the stream stores after every other set-ending
        tiebreak. The response field `ends_at_final` says whether the
        sequence served ends on the match-closing point: `false` on a
        completed match whose stream stops short of it — a retirement or
        walkover (no closing point was played), a capture that stopped two
        or more points short, or a closer that cannot be stated as one point
        (from deuce, or from a 10-point match tiebreak). Always `false` on a
        live match. On the
        `reconstruction` basis it is judged from the projected sequence's
        last frame (a complete recorded sequence of a retired match ends at
        the retirement, so it reads `false` there). WebSocket and push
        frames are unchanged.


        REVISIONS: `changed_since` (added 2026-09-20). `after_seq` is a
        cursor by `seq`, so it can never return a row you already hold — and
        a `serve`/`outcome` tag that lands late lands on exactly such a row.
        Every row now carries `tagged_at`, the UTC instant its tags landed
        (null while none has). Pass `changed_since=<ISO-8601 instant>` (e.g.
        `2026-09-20T00:35:18Z`; `Z` or an offset, a naive value is read as
        UTC, a date alone is refused) to get only the rows whose `ts` OR
        `tagged_at` is later than that instant, in `seq` order, paged like
        any other read and composable with `after_seq`. The post-match
        recipe: read the match, keep the instant, re-read with
        `changed_since=<that instant>` and replace the rows you hold by
        `seq` — no socket, no full re-fetch. Anything that is not an
        ISO-8601 timestamp is a 400 `bad_changed_since`. On the
        `reconstruction` basis no row carries a clock or a tag, so a
        `changed_since` read of it is an empty page: that sequence is final
        at first read.
      operationId: getMatchPoints
      parameters:
        - $ref: "#/components/parameters/matchId"
        - name: after_seq
          in: query
          required: false
          schema: { type: integer, minimum: 0, default: 0 }
          description: >-
            Return only points with `seq` greater than this — the resume
            cursor. Pass the `last_seq` of the previous page (or the last seq
            your WS stream delivered) to continue; 0 or absent reads from the
            start of the match. A non-integer or negative value is a 400
            `bad_after_seq`.
        - name: changed_since
          in: query
          required: false
          schema: { type: string, format: date-time }
          description: >-
            Added 2026-09-20. Return only rows whose `ts` OR `tagged_at` is
            later than this instant — the revision filter for a reader
            without a socket, composable with `after_seq`. ISO-8601 with a
            `Z` or an offset (e.g. `2026-09-20T00:35:18Z`); a naive value is
            read as UTC; a date alone is not an instant and is refused.
            Anything that is not an ISO-8601 timestamp is a 400
            `bad_changed_since`. An empty page on the `reconstruction`
            basis, whose rows carry neither a clock nor a tag.
      responses:
        "200":
          description: The point events page, seq order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/MatchPoints" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /players:
    get:
      summary: Search players by name (FREE)
      operationId: searchPlayers
      parameters:
        - name: search
          in: query
          schema: { type: string }
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Players (ranked first; no stats object on the list)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Player" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /players/{playerId}:
    get:
      summary: One player's bio + ranking + cached stats (FREE)
      description: >-
        `playerId` is a ROSTER id — the live player registry, the id space
        `/players`, `/matches` and `/rankings` all speak.

        It is NOT the archive corpus person id. The results archive
        (1968–2022) keeps its own person registry, and archive match rows
        publish those ids as `winner.player_id` / `loser.player_id`. The two
        spaces are disjoint: no corpus id resolves here, and since 2026-09-20
        a 404 for one says so and points at
        `/history/archive/players?id={playerId}`, which is where that id is
        read. A 404 with no `see` field is simply an id we do not hold.
      operationId: getPlayer
      parameters:
        - name: playerId
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Player with `stats` ({ratings, season})
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Player" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: >-
            No roster player holds this id. When the id IS a corpus person id
            the body adds `detail` and `see` (the archive lookup); otherwise it
            is the plain `Error` body.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PlayerNotFound" }
        "410":
          $ref: '#/components/responses/PlayerGone'
        "429": { $ref: "#/components/responses/RateLimited" }
  /tournaments:
    get:
      summary: Tournament catalogue — the id space `Match.tournament_id` joins (FREE)
      description: >-
        Stable tournament identity, one row per tournament × event type, stable
        across seasons. `city`/`country` come from a curated table and
        `category` only where our catalogues agree unambiguously on an
        exact-name join — each is null otherwise, never derived from the
        tournament name. Each row also carries the CURRENT season's `tier` /
        `tier_source` (added 2026-09-22) — the level in a closed vocabulary
        (`atp_500`, `challenger_125`, `wta_125`, `itf_w35` … | null); the
        tier is per season, so a match carries its own.
      operationId: listTournaments
      parameters:
        - name: search
          in: query
          schema: { type: string }
          description: Case-insensitive substring match on the tournament name.
        - $ref: "#/components/parameters/tour"
        - $ref: "#/components/parameters/draw"
        - name: tier
          in: query
          required: false
          schema: { type: string }
          description: >-
            Tier filter (added 2026-09-24): comma-separated exact values from the
            same closed tier vocabulary as `Match.tier` (`?tier=atp_500`,
            `?tier=atp_500,challenger_100`). Selects tournaments whose own `tier`
            field carries one of the values, which on this resource is the
            **current season's** level, because a catalogue row has no season of
            its own. That is the one difference from `?tier=` on `/matches` and
            `/history/matches`, where the value is the level in each MATCH'S
            season (a tournament keeps one `tournament_id` while its level
            moves). Filter and field always read the same season on the same
            resource, so they cannot disagree. A tournament with no row for the
            current season matches no value: null means the level is unknown,
            not absent. Composes with `?tour=`, `?draw=` and `?search=`. Unknown
            value → 400 `bad_tier` with the offending values in `bad` and the
            full vocabulary in `allowed`.
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Tournaments, name order
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Tournament" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /tournaments/{tournamentId}:
    get:
      summary: One tournament by its stable id (FREE)
      operationId: getTournament
      parameters:
        - name: tournamentId
          in: path
          required: true
          schema: { type: string }
          description: The `tournament_id` carried on match objects.
      responses:
        "200":
          description: The tournament
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Tournament" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /markets:
    get:
      summary: The match's match-winner market (PRO)
      description: >-
        The match-winner market mapped to this match — `data` holds at most one
        object, and `meta.count` is 0 when nothing is mapped.


        MATCH-WINNER ONLY. No handicaps or game spreads, no totals, no
        set-winner books, and no per-game or per-set derivative of any kind.
        A quote here is the probability that a player WINS THE MATCH. Venues
        do list tennis derivatives beside the match-winner book — game spreads
        such as "A (-3.5) vs B (+3.5)" among them — and this API deliberately
        publishes none of them: a derivative is refused at the mapping step so
        it can never be served as, or beside, a match-winner price
        (2026-09-22).
      operationId: listMarkets
      parameters:
        - name: match_id
          in: query
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Markets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Market" }
                  meta:
                    type: object
                    properties:
                      match_id: { type: integer }
                      count: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /markets/{matchId}/prices:
    get:
      summary: Market + recent price ticks per side, newest first (PRO)
      description: >-
        The mapped match-winner market for one match, with its recent price
        ticks per side, newest first.


        404 with `error: no_market` (since 2026-09-02; `match_id` and
        `coverage: "none"` alongside) when no match-winner market is mapped to
        the match — a market is mapped only where one is published for that
        fixture, so a client walking every live match will meet this. A bare
        `not_found` means the match id itself does not exist. Every row of
        `GET /matches` carries `has_market`, so a slate can be filtered before
        any call here. `GET /matches/{matchId}`
        answers `200` for the same match with `market` and `market_price` set
        to `null` instead, and carries the live score in the same response, so
        a per-match poll built on the detail route never spends a call on a
        404.


        Ticks are kept for 30 days and then deleted: a market older than that
        answers with an empty `prices` array while staying mapped — retention,
        not a fault. For paging past 500 ticks use `/matches/{matchId}/prices`
        with its cursor.
      operationId: getMarketPrices
      parameters:
        - $ref: "#/components/parameters/matchId"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Market with `prices`
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Market" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404":
          description: >-
            `error: not_found` — no such match id. `error: no_market` (with
            `match_id`, `coverage: "none"`, `detail`) — the match exists and no
            match-winner market is mapped to it; `has_market` on the match list
            says so without a probe.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /matches/{matchId}/prices:
    get:
      summary: Bare price ticks of the mapped match-winner market, newest first (PRO)
      description: >-
        Recent ticks only (no market wrapper). `limit` caps at 500; `minutes` bounds the lookback
        window; `cursor` pages an older match. 404 `no_market` when the match exists but has no
        mapped market (404 `not_found` for an unknown id). Retention (since 2026-09-15): in-play
        ticks of a match with a mapped market — from live to completion, plus a five-minute pad —
        are kept at full resolution and not deleted; pre-match / idle ticks and unmapped markets
        keep the tiers (every tick for an hour, ~1/minute to 24h, ~1/5 minutes after, deleted after
        30 days). Ticks stamped before 2026-09-15 were already thinned under those tiers.


        Ticks are kept for 30 days and then deleted, so a match older than
        that answers an empty `data` while its market stays mapped — that is
        retention, not a fault. Past 500 ticks, page with the cursor: read a
        page, and while `meta.has_more` is true pass `meta.next_cursor` back as
        `?cursor=` for the next (older) page. Pages never overlap or skip a
        tick (added 2026-09-09).
      operationId: listMatchPrices
      parameters:
        - $ref: "#/components/parameters/matchId"
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 500, default: 100 }
        - name: minutes
          in: query
          schema: { type: integer, minimum: 1, maximum: 1440 }
        - name: cursor
          in: query
          schema: { type: string }
          description: >-
            Keyset cursor for the next (older) page — the `meta.next_cursor` of
            the previous page (added 2026-09-09). Opaque; anything else is
            `400 bad_cursor`.
      responses:
        "200":
          description: Price ticks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Price" }
                  meta:
                    type: object
                    properties:
                      match_id: { type: integer }
                      count: { type: integer }
                      has_more:
                        type: boolean
                        description: >-
                          The window was clipped at limit — older ticks exist.
                          There is no offset here: pass `next_cursor` back as
                          `?cursor=` for the next older page.
                      next_cursor:
                        type: [string, "null"]
                        description: >-
                          Present (non-null) exactly when `has_more` is true —
                          pass it back as `?cursor=` for the next older page
                          (added 2026-09-09).
                      limit: { type: integer }
                      minutes: { type: [integer, "null"] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/matches/{matchId}/prices:
    get:
      summary: Per-point price history — the match-winner quote in force at every played point (PRO)
      operationId: listHistoryMatchPrices
      description: >-
        One row per played point of a match with a mapped market, ascending by `seq` (added
        2026-09-15). Each row carries the score state the BASIC tape publishes and, per neutral side
        ("1" = players.p1's outcome, "2" = p2's), the newest quote observed at or before the point's
        capture time — or, when none precedes it, the first quote after it within five minutes
        (negative lag). A side with no usable quote is null, never invented. `resolution` is an
        honest label of the join: tick (|lag| <= 15 s), minute (<= 90 s), coarse (older); matches
        played from 2026-09-15 align against the full-resolution in-play tape, earlier ones against
        the thinned tape and read minute/coarse. The ULTRA-only per-point fields (server, winner,
        serve, outcome) are not on this surface. Works on a live match too. 404 `no_market` when the
        match has no mapped market — enumerate with `GET /history/matches?has_market=true`.
      parameters:
      - $ref: '#/components/parameters/matchId'
      - name: after_seq
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Resume cursor — return points with seq greater than this (meta.last_seq of the
          previous page). Anything but a non-negative integer is a 400 bad_after_seq.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      responses:
        '200':
          description: Per-point price rows, ascending by seq
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PointPrice'
                  meta:
                    type: object
                    properties:
                      match_id:
                        type: integer
                      count:
                        type: integer
                      limit:
                        type: integer
                      last_seq:
                        type: integer
                        description: The resume cursor — pass back as ?after_seq= while has_more is true.
                      has_more:
                        type: boolean
                      alignment:
                        type: string
                        enum:
                        - points
                        - none
                        description: points = the match has a per-point stream to align to; none = it has
                          none (a reconstruction-only tape carries no point clock and no quote is
                          fabricated — data is empty, not an error).
                      resolution_counts:
                        type: object
                        properties:
                          tick:
                            type: integer
                          minute:
                            type: integer
                          coarse:
                            type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/UpgradeRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/MatchGone'
        '429':
          $ref: '#/components/responses/RateLimited'
  /history/matches:
    get:
      summary: Completed matches, newest first, with derived winner and tape coverage (BASIC)
      description: >-
        Requires BASIC on the live API, or any Historical Data API plan
        (Starter and up — see https://livetennisapi.com/historical-tennis-data-api).
        A FREE key may spend its 20 free history calls per calendar month here;
        past that the answer is `403 upgrade_required` carrying
        `free_history_taste: "used"`.
        All tours, January 2023 → now (deeper results live in the results
        archive, 1968–2022, at `/history/archive/matches`). Filter to a date
        range with `from`/`to`, and by `tour`, `draw` (singles/doubles),
        `player` (either participant) and `country` — same vocabulary as
        `/matches`. Each item carries a
        `tape` object saying what point-by-point data we hold for that match,
        so a whole page can be qualified in one call instead of one request per
        match. NOTE `?coverage=` is applied AFTER the page is cut, so a
        filtered page is routinely shorter than `limit` (and may be empty)
        while later pages still hold matching matches — a short filtered page
        is not an end-of-data signal; `?points_complete=` filters the same
        way. `?tier=` (added 2026-09-22) selects by the level the tournament
        was played at in the match's season, and `?restated_since=` (added
        2026-09-22) keeps only the matches whose published result was
        corrected after an instant — the poll to run after each settlement
        pass.
      operationId: listCompletedMatches
      parameters:
        - $ref: '#/components/parameters/hasMarket'
        - $ref: "#/components/parameters/isQualifying"
        - $ref: "#/components/parameters/gender"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/playedFrom"
        - $ref: "#/components/parameters/playedTo"
        - $ref: "#/components/parameters/tour"
        - $ref: "#/components/parameters/draw"
        - $ref: "#/components/parameters/player"
        - $ref: "#/components/parameters/country"
        - $ref: "#/components/parameters/tournamentId"
        - $ref: "#/components/parameters/tier"
        - name: coverage
          in: query
          required: false
          schema: { $ref: "#/components/schemas/Coverage" }
          description: >-
            Keep only matches whose tape has this coverage. An unknown value is
            a 400 `bad_coverage` listing the accepted values in `allowed`.
        - name: points_complete
          in: query
          required: false
          schema: { type: string, enum: ["true", "false"] }
          description: >-
            Keep only matches whose measured point-completeness ledger verdict
            is this value — best-basis (the served tape OR an on-disk
            reconstruction measured point-complete; fetch the latter with
            `?points=complete` on the per-match tape). The ledger is a
            per-match cache reconverged nightly. A match not yet measured
            matches NEITHER value; anything but true/false is a 400
            `bad_points_complete`. Applied AFTER the page is cut, exactly like
            `?coverage=`.
        - name: restated_since
          in: query
          required: false
          schema: { type: string, format: date-time }
          description: >-
            Keep only matches whose published result was CORRECTED after this
            instant (added 2026-09-22) — a `restatement` row on their status
            history later than it. The poll to run after recording results:
            anything it returns has a `result_restated_at` past your cursor
            and a `result_version` above the one you hold, and its status
            history says what changed. An ISO-8601 instant with a `Z` or an
            offset (a naive value is read as UTC); a bare date is a 400
            `bad_restated_since` — a day is not an instant, exactly as for
            `changed_since`. Composes with every other filter here. A match
            whose correction was a reopen is `live` again and reappears here
            once re-completed, with a further `restatement` row. Rows with
            this basis exist from 2026-09-22; earlier corrections were not
            signalled and nothing is reconstructed for them.
      responses:
        "200":
          description: Completed matches (`winner` = 1|2|null, from final sets), each with its tape coverage
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/HistoryMatch" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/coverage:
    get:
      summary: Measured completeness rollup per tour × draw bucket (BASIC)
      description: >-
        Requires BASIC on the live API, or any Historical Data API plan
        (Starter and up — see https://livetennisapi.com/historical-tennis-data-api).
        A FREE key may spend its 20 free history calls per calendar month here;
        past that the answer is `403 upgrade_required` carrying
        `free_history_taste: "used"`.
        The numbers to read BEFORE choosing what to backtest, in one call
        instead of paging the archive. A PREBUILT snapshot rebuilt nightly
        right after the completeness ledger reconverges — never computed at
        read time — so `as_of` (= `built_at`) dates every number, and
        `ledger_max_computed_at` is the newest underlying per-match
        measurement. Buckets are atp/wta/challenger/itf/juniors ×
        singles/doubles plus `other` (team ties, mixed, exhibitions, and
        matches with no stated event type — counted, never dropped, so the
        totals cannot lie), derived from the same registries as the `tour` and
        `draw` fields. `method` states the full measurement rule in one
        paragraph, so every number carries its own definition. As of
        2026-08-18 the headline spread it exposes: 51.1% of ITF singles
        matches are point-complete on the best basis against 3.5% of ITF
        doubles — do not extrapolate a completeness rate across a tour group.
      operationId: getHistoryCoverage
      responses:
        "200":
          description: The rollup artifact, dated by its own as_of
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CoverageRollup" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503":
          description: >-
            coverage_unavailable — the artifact has not been built yet (or is
            unreadable). Honest and temporary; retry after the nightly build.
            The rollup is never computed inline.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /history/matches/{matchId}:
    get:
      summary: Per-match tape — point-by-point score + per-point model probabilities (BASIC)
      description: >-
        The tape is the point-by-point score sequence we hold for this match —
        every recorded score row including the model fields
        `win_probability_p1` and `danger` at that point — plus match metadata
        and the model profiles produced during the match. The model fields here
        are part of the paid History product by design, distinct from the
        ULTRA-gated LIVE model fields. One match per request. Requires BASIC on
        the live API, or the Historical Data API Starter plan and up.


        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, in commit order —
            deliberately non-monotonic, since independent sources race and a
            higher-trust one may correct a lower-trust one backwards. `clean`
            returns one row per distinct score state, keeping the last
            assertion of each, ordered by MATCH PROGRESS (the same ranking
            our arbiter uses), not by wall clock — so array order is the
            authoritative point order, and `timestamp` values may locally
            disagree with it by a few seconds where a stale re-assertion
            carried a later clock. Within a game, deuce states legitimately
            cycle (40-40 ↔ AD) and rank equally, so consecutive clean rows
            are not guaranteed point-monotonic there; `point_winner` is only
            set where the transition is a single attributable point. `winner`
            (since 2026-09-22) rides every row of EITHER sequence with the
            same verdict: on the raw sequence it is judged against the
            previous raw row, so a re-send reads null there and collapses away
            here. An
            unknown value is a 400 `bad_sequence`.
        - name: points
          in: query
          required: false
          schema: { type: string, enum: [default, complete], default: default }
          description: >-
            `default` serves observed rows first — what our own pipeline
            committed, a SAMPLED record of the match. `complete` is the
            explicit opt-out of that precedence for consumers who want every
            point: where a whole-match reconstruction exists it is served
            WHOLE, in its own point order, with `point_winner` (and `winner`,
            the same verdict) on every row
            and null timestamps/model fields per the reconstruction contract.
            Where none exists, the response is exactly the default read plus
            `meta.points` (whose `available_complete` tells the cases apart) —
            no error. Cannot combine with `sequence=clean` (400
            `bad_combination` — the state-key collapse would delete the
            repeated deuce states a complete point sequence contains). An
            unknown value is a 400 `bad_points`; where not yet enabled,
            `complete` answers 400 `points_read_disabled` rather than silently
            serving the default. `coverage` and `meta.points` are orthogonal
            axes: coverage says how the rows were OBTAINED, points says how
            COMPLETE the sequence is — completeness is only ever claimed per
            match, as measured.
      responses:
        "200":
          description: The full tape (`match` + `tape` + `profiles` + coverage `meta`)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/HistoryTape" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/incidents:
    get:
      summary: Published data-quality incidents (BASIC)
      description: >-
        Every data-quality incident we have published, oldest window first.
        This is the register to reconcile against when a published value
        changed after you read it: each record states the window it applies
        to, the rule before and after, what the defect was, which surfaces it
        touched, how to tell an affected row from a clean one, and whether
        corrections and a per-match list are available.
        Nothing here is inferred at read time. The register is part of a
        release, so a record appears only when we have decided what it says,
        and it does not change between releases.
      operationId: listHistoryIncidents
      responses:
        "200":
          description: The incident register.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Incident" }
                  meta:
                    type: object
                    properties:
                      count: { type: integer }
                      kinds:
                        type: array
                        items: { type: string }
                      generated_at: { type: string, format: date-time }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/incidents/{incidentId}/matches:
    get:
      summary: The matches one incident affected, as JSONL or CSV (BASIC)
      description: >-
        One row per affected match, streamed as JSONL by default or CSV with
        `?format=csv`. Columns are `incident_id`, `match_id`, `tournament`,
        `tour`, `round`, `draw_stage`, `scheduled_time`, `affected_field`,
        `served` and `expected`. `served` and `expected` carry that incident's
        own vocabulary: for the deciding-set rule `match_tiebreak` against
        `full_set`, for the price side `side_reversed` against `side_players`,
        and for a field repair the before and after values.
        Rows are derived from stored data by the same code every consumer of
        that field uses. A match whose derivation would be a guess is left
        out, and the incident's `matches.note` says which those are, so this
        export is exact rather than complete.
      operationId: listIncidentMatches
      parameters:
        - name: incidentId
          in: path
          required: true
          schema: { type: string }
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [jsonl, csv]
            default: jsonl
      responses:
        "200":
          description: >-
            One row per affected match, as a file attachment.
          content:
            application/x-ndjson:
              schema: { type: string }
            text/csv:
              schema: { type: string }
        "400":
          description: "`bad_format` — `format` was neither `jsonl` nor `csv`."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404":
          description: >-
            `not_found` for an unknown incident id. `not_derivable` for an
            incident with no exact per-match derivation, carrying that
            incident's `window_utc`, `affected_surfaces` and the note saying
            why.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/archive/matches:
    get:
      summary: Results archive (1968–2022) — deep historical results (BASIC)
      description: >-
        Completed-match RESULTS from a licensed historical corpus — ATP and
        WTA main draws, qualifying/challengers and futures tiers, 1968 through
        2022. Winner/loser-shaped records with final score, round, seeds, the
        players' ranks AT THE TIME, and per-match serve statistics where the
        era recorded them. Requires BASIC on the live API, or any Historical
        Data API plan (Starter and up).


        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. A result played 2013–2022 may also have a
        reconstructed point-by-point tape at
        `/history/archive/matches/{archiveId}/tape`; the RESULT stays on BASIC
        either way.
      operationId: getArchiveMatch
      parameters:
        - name: archiveId
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: The archive record, `stats` included where the era recorded them
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ArchiveMatch" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/archive/matches/{archiveId}/tape:
    get:
      summary: >-
        Reconstructed 2013–2022 point-by-point tape for one archive result
        (ULTRA, or any History plan)
      description: >-
        The score sequence behind a 2013–2022 archive result, REBUILT FROM THE
        PUBLIC RECORD. The result tells you what happened; this tells you how.


        NOBODY WATCHED THESE MATCHES, and every field that would imply
        otherwise is null. `timestamp` is null on every row — not by
        convention, but because the production table has no timestamp column at
        all, so no repair, backfill or re-archive can put a wall clock on a
        2016 row, and the promotion script refuses to run if such a column ever
        appears.
        `win_probability_p1` and `danger` are null on every row: the model was
        not running in 2016 and nothing has been back-computed and served as if
        it had been (`meta.model_rows` and `meta.observed_rows` are both 0,
        always). `profiles` is always `[]`. The rule we publish for the 2023+
        tape — a non-null `timestamp` means we watched that point live — holds
        across both halves of the product.


        YEARS: 2013–2022 ONLY. 97,901 matches and 14,340,663 rows. The results
        archive holds a further 977,903 matches from 1968–2012 and NONE of them
        has a tape — there is no public point-by-point record of those years to
        rebuild and we do not manufacture one. A match with no tape answers
        404, which is also the answer when a tape exists and failed the proof
        below; the two are deliberately not distinguished.


        COVERAGE OF THE ERA, thin spots beside the strong ones: 19.3% of
        archive matches played 2013–2022 overall, 44.9% of tour-level play.
        Main-draw tour buckets run 91.6–98.7% (ATP Masters 98.7%, ATP slam
        98.0%, WTA Premier Mandatory 97.9%, WTA slam 97.4%, ATP 250–500 95.4%,
        WTA Premier 94.1%, WTA International 91.6%); ATP Challenger main draws
        55.3% and Challenger qualifying 33.6%; slam QUALIFYING is thin at 16.0%
        (ATP) and 18.1% (WTA); ITF and futures are effectively absent — 25 of
        116,575 ATP futures matches, 68 of 19,162 ITF M15, 48 of 9,380 ITF M25
        — and this product does not cover them. If your work is ITF, this is
        the wrong dataset and we would rather you knew now. 31.0% of the corpus
        is qualifying-draw play, which is unusual at this scale and is the part
        you are least likely to hold already.


        HOW A TAPE IS BOUND TO ITS MATCH. A tape attached to the wrong match is
        silent, permanent and poisons anything trained on it, so each one
        proves five things before publication: the EDITION binds by majority
        vote onto one archive tournament; the NAMES resolve to exactly one
        archive row with an unambiguous orientation; the ROUND agrees through
        an explicit map (this is what separates the qualifying and main-draw
        meetings of the same pair inside one edition); the SET SPINE derived
        from the rows equals the published final score exactly (a retirement
        matches on a one-directional prefix rule — a tape may stop short, never
        run past the printed score); and the vendor DATE lies inside the
        tournament's window. The tape is then walked step by step against 23
        interior invariants — games and sets never regress or jump, a closed
        set holds a score a set can actually finish on, a tiebreak is flagged
        only where one can be played, points never run backwards inside a game,
        `seq` is contiguous. A tape that fails any clause or any invariant is
        REFUSED WHOLESALE rather than published against a guess, which is why
        this endpoint answers 404 instead of serving a probable match.


        `archiveId` is an `archive_matches.id` (the `id` on a
        `/history/archive/matches` row), NOT a match id — the two are separate,
        overlapping integer spaces, so passing one to the other's routes
        resolves a different, real record without erroring. The response names
        it `meta.archive_match_id` for exactly that reason. Rows are
        WINNER-FIRST (`sets[0]` / `games[0]` / `points[0]` are the winner's,
        `server: 1` means the winner was serving), unlike the p1/p2-shaped
        2023+ tape — a live match has no winner while it is being played.


        This operation takes NO query parameters: `sequence` and `points` are
        ignored rather than refused. `meta.sequence` is always `raw` — a
        reconstructed tape has one source and no corrections, so there is
        nothing for a clean collapse to remove.


        Tier: core ULTRA, or any active History plan (Starter included, which
        opens it on a FREE core key). The archive RESULT itself
        (`GET /history/archive/matches/{archiveId}`) stays on BASIC — core
        BASIC and core PRO read the result and are refused the tape, and the
        refusal is `403 upgrade_required` carrying `capability: archive_tape`.
        The per-year BULK files (`?kind=archive_tape`) are a separate gate:
        core ULTRA, or a History Pro/Business subscription, or an active
        one-off package window.
      operationId: getArchiveTape
      parameters:
        - name: archiveId
          in: path
          required: true
          description: >-
            An `archive_matches.id` — the `id` on a
            `/history/archive/matches` row, never a match id.
          schema: { type: integer }
      responses:
        "200":
          description: >-
            The reconstructed tape (`match` + `tape` + `tiebreaks` +
            an always-empty `profiles` + provenance `meta`)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ArchiveTape" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404":
          description: >-
            No tape for this archive result — it is 1968–2012, it is
            2013–2022 and was never reconstructed, or a reconstruction exists
            and did not prove its binding. The three are deliberately not
            distinguished: "we hold something we will not stand behind" is not
            a state this product reports.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/archive/players:
    get:
      summary: Archive player bios — hand, DOB, country, height, career-high (BASIC)
      description: >-
        People of the results archive (1968–2022), in their own id space —
        `id` is the corpus person id that archive match rows carry as
        `winner.player_id` / `loser.player_id`, scoped per tour; never a
        roster id. Career-high rank and the earliest week it was reached are
        computed offline from the corpus's own weekly ranking tables. Null
        fields are the era's silence, never guessed. Requires BASIC, or any
        Historical Data API plan.
      operationId: listArchivePlayers
      parameters:
        - name: id
          in: query
          schema: { type: integer }
          description: >-
            Look a person up BY the corpus person id — the value archive match
            rows publish as `winner.player_id` / `loser.player_id`. This is the
            only place that reads the PERSON by that id; the one other surface
            taking it, `/rankings?archive_player=`, is ULTRA, requires
            `system=elo`, and answers with ratings rather than a bio. Corpus
            ids and roster ids are disjoint id spaces, so the same value on
            `/players/{playerId}` returns 404 (that 404 now points here).
            Returns every person wearing the id — the tours number
            independently and some ids are live in both — so add `tour` to
            narrow it to exactly one, the same rule `archive_player=` applies.
        - name: player_id
          in: query
          schema: { type: integer }
          description: >-
            Alias of `id`, under the name the same value carries on an archive
            match row. Sending both with different values is a 400.
        - name: name
          in: query
          schema: { type: string, minLength: 3 }
          description: Case-insensitive substring filter (min 3 chars).
        - name: tour
          in: query
          schema: { type: string, enum: [atp, wta] }
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: Archive people, ordered by name
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/ArchivePlayerBio" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/archive/career:
    get:
      summary: Career aggregates over the results archive, 1968–2022 (BASIC)
      description: >-
        One player's whole archive career in one response: W-L record
        (overall, by surface, by level, by year), titles, and the summed
        serve-stat block with derived ratios. Everything is a sum or a ratio
        of sums over rows you can fetch individually from
        `/history/archive/matches` — nothing is modelled.
        `serve.matches_with_stats` states the coverage honestly: the corpus
        records per-match serve statistics from 1991 only, so a 1970s career
        has a full W-L record and an empty serve block. Ambiguous name
        fragments are refused with candidates, and an exact name selects its
        person even where a longer name contains it (same rule as `/h2h`); an
        unknown name is a 404. Requires BASIC, or any Historical Data API
        plan.
      operationId: getArchiveCareer
      parameters:
        - name: name
          in: query
          required: true
          schema: { type: string, minLength: 3 }
          description: >-
            Player name (fragment, min 3 chars — must resolve to one person).
      responses:
        "200":
          description: The career aggregate body
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ArchiveCareer" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /h2h:
    get:
      summary: >-
        Head-to-head across the results archive (1968–2022) and our own
        completed matches (2023→now) (BASIC)
      description: >-
        The record between two players, assembled from BOTH halves of the
        product: the results archive, where the winner is a stored column, and
        our own completed matches, where the winner is derived from the final
        recorded state. Names are the keys — archive people have no roster
        ids. A fragment matching more than one player is refused with the
        candidate list (`400 ambiguous_name`), because two people summed into
        one record is a wrong answer, not a convenience. Passing a name
        EXACTLY selects that person, even where a longer name contains it, so
        `Carlos Alcaraz` resolves although `Carlos Alcaraz Gonzalez` also
        exists. A name you did not type in full stays a fragment: `Sinner`
        still refuses, and lists Jannik and Martin. Totals count meetings
        with a KNOWN winner; `undecided` counts the rest. Walkovers and
        retirements are part of the record, and each meeting carries `outcome`
        so you can exclude them. Requires BASIC, or any Historical Data API
        plan. On ULTRA, a per-player `stats` block adds serve/return/break-point
        aggregates over the pairing: `archive_serve` (serve-side, from 1991)
        and `current` (2023+, adding return and break-point conversion, aces
        and winners), each with `meetings_with_stats`.
      operationId: getHeadToHead
      parameters:
        - name: p1
          in: query
          required: true
          schema: { type: string, minLength: 3 }
          description: First player name (fragment, min 3 chars).
        - name: p2
          in: query
          required: true
          schema: { type: string, minLength: 3 }
          description: Second player name (fragment, min 3 chars).
      responses:
        "200":
          description: >-
            The head-to-head record; empty totals when no player matches the
            names
          content:
            application/json:
              schema: { $ref: "#/components/schemas/HeadToHead" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/packages:
    get:
      summary: List the pre-built monthly bulk history packages (PRO)
      description: >-
        Bulk downloads are a heavier product than single-match tape reads.
        Requires PRO on the live API, or the Historical Data API Pro plan and
        up, or a one-off package access pass. A key that can read the tape but
        is not package-entitled receives `403 upgrade_required`.
      operationId: listHistoryPackages
      parameters:
        - name: kind
          in: query
          required: false
          schema: { type: string, enum: [tape, rankings, rally, archive, elo, archive_tape], default: tape }
          description: >-
            Package family. `tape` (default) = monthly point-by-point match
            tapes; `rankings` = as-of ranking records (ULTRA); `rally` = the
            charted rally corpus (shot-by-shot) as YEARLY exports (ULTRA);
            `archive` = the results archive (1968–2022) as YEARLY exports,
            same entitlement as the tape packages; `elo` = the as-of Elo tape
            as YEARLY exports (ULTRA); `archive_tape` = the RECONSTRUCTED
            2013–2022 point-by-point tape as YEARLY exports — ten periods, 2013
            through 2022, each with a JSONL and a CSV file, all `ready`,
            needing ULTRA or a
            History Pro/Business subscription or an active one-off package
            window (a History Starter grant reads a tape per call and does not
            download years of them). The yearly kinds' `period`
            is `YYYY`, one file per year, because a fixed historical corpus is
            not an accruing monthly stream. The default means a tape-only
            client never sees a new kind of row appear.
        - name: year
          in: query
          required: false
          schema: { type: string, pattern: '^\d{4}$' }
          description: >-
            Year archive listing — every published month of the year (History
            Business, a 1-year package, or ULTRA).
      responses:
        "200":
          description: Ready packages, newest period first
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/HistoryPackage" }
                  meta:
                    type: object
                    properties:
                      count: { type: integer }
                      year:
                        type: string
                        description: Echoed only when `?year=` was supplied.
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /history/packages/{period}:
    get:
      summary: One monthly package — manifest, or the bulk file itself (PRO)
      description: >-
        Without `format` returns the package manifest (file set, counts,
        sha256). With `format=jsonl` or `format=csv` streams that file as an
        attachment. Same entitlement as `/history/packages`. 404 when the
        month has not been built yet — list available months first.
      operationId: getHistoryPackage
      parameters:
        - name: period
          in: path
          required: true
          description: >-
            Calendar month, `YYYY-MM` — except for the yearly kinds (`rally`,
            `archive`, `elo`, `archive_tape`), where it is the bare year
            `YYYY` (`400 bad_period` otherwise).
          schema: { type: string, pattern: '^\d{4}(-\d{2})?$' }
        - name: kind
          in: query
          required: false
          schema: { type: string, enum: [tape, rankings, rally, archive, elo, archive_tape], default: tape }
          description: >-
            Package family; `rankings`, `rally`, `elo` and `archive_tape` require ULTRA, a History
            Pro/Business subscription, or an active one-off package window (changed 2026-08-19).
            `rally` = the yearly charted rally corpus exports; `archive` =
            the yearly results archive (1968–2022) exports, same entitlement
            as the tape packages; `elo` = the yearly as-of Elo tape exports;
            `archive_tape` = the yearly reconstructed 2013–2022 point-by-point
            tape exports (`period` 2013 through 2022 — no other year exists).
        - name: format
          in: query
          required: false
          description: >-
            Omit for the JSON manifest; set to download the file. `corrections`
            (added 2026-09-10) streams the package's correction CSV — `match_id,
            field, before, after, tournament_key, source, corrected_at` — when
            stored data was repaired after the package was published; the
            manifest's `files` lists it with `format: corrections`, and a
            package without one answers 404 `no corrections file for that
            package`. First use: the 2023-02 → 2024-12 tape packages carry
            `surface` corrections for 19,439 Challenger matches (repaired
            2026-09-10; the packages themselves were rebuilt the same day).
          schema: { type: string, enum: [jsonl, csv, corrections] }
      responses:
        "200":
          description: >-
            The manifest (no `format`), or the bulk file as an attachment
            (`format=jsonl` streams NDJSON, `format=csv` streams CSV,
            `format=corrections` streams the correction CSV). A
            gzipped file (see the manifest's `compression`) is served as
            `application/gzip`, never with `Content-Encoding: gzip` — the
            manifest's `sha256` covers the exact bytes you receive.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/HistoryPackage" }
            application/x-ndjson:
              schema: { type: string, format: binary }
            text/csv:
              schema: { type: string, format: binary }
            application/gzip:
              schema: { type: string, format: binary }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /fixtures:
    get:
      summary: Upcoming scheduled fixtures, earliest first (FREE)
      operationId: listFixtures
      parameters:
        - $ref: "#/components/parameters/tour"
        - $ref: "#/components/parameters/draw"
        - $ref: "#/components/parameters/isQualifying"
        - $ref: "#/components/parameters/gender"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
      responses:
        "200":
          description: >-
            Fixtures with start time and player ids where resolved — the
            nulls are real states, not gaps (names are always present)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Fixture" }
                  meta: { $ref: "#/components/schemas/ListMeta" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /usage:
    get:
      summary: Your own usage vs quota (FREE — any tier)
      description: >-
        Durable daily usage for the calling key: tier, limits, today's calls
        (current to the second) and a 30-day history. The per-minute window is
        on the X-RateLimit-* headers of every response, not here. Calls to this
        endpoint are quota-exempt — checking your usage never consumes it.
      operationId: getUsage
      responses:
        "200":
          description: Usage summary
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Usage" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /rankings:
    get:
      summary: Rankings and Elo — rank-ordered listing (PRO) or per-player as-of records (ULTRA); the as-of Elo tape is ULTRA in both modes
      description: >-
        Returns, per ranking system, the newest record effective ON OR BEFORE
        `as_of` — never one dated after it. Every other ranking field in this
        API is the player's CURRENT value joined at read time, so replaying an
        old match elsewhere shows today's ranks; this endpoint is the
        point-in-time answer. Systems are never collapsed into a single "rank":
        ATP/WTA and the ITF circuits carry rank+points, UTR carries a rating
        with null rank and points because it has neither.
        `meta.coverage.oldest_available` gives the earliest date each system
        can answer for — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29) and nothing earlier can be reconstructed.


        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.
            On an OFFICIAL system it is accepted when it agrees with that
            system's own tour (`system=atp&tour=atp`) and REFUSED with 400
            when it contradicts it. CORRECTION 2026-09-20: until that date
            `system=atp&tour=wta` returned 200 and the ATP table — the
            parameter was accepted and ignored. If you sent a contradicting
            pair, the rows you received were the table named by `system`.
        - name: surface
          in: query
          required: false
          schema:
            type: array
            items: { type: string, enum: [overall, hard, clay, grass] }
          explode: true
          description: >-
            `system=elo` only. Listing mode takes exactly one (default
            `overall`); per-player mode is repeatable and defaults to all
            four ladders. A ladder the player has never played is omitted,
            never substituted. REFUSED with 400 when no requested system is
            `elo` — there is no clay ATP ranking, so the filter cannot be
            made to act. CORRECTION 2026-09-20: until that date
            `system=atp&surface=clay` returned 200 and the OVERALL ATP
            table. A mixed `system=atp&system=elo&surface=clay` still
            passes, because an elo system is present.
        - name: min_matches
          in: query
          required: false
          schema: { type: integer, minimum: 0, default: 20 }
          description: >-
            `system=elo` listing only. Minimum matches on that ladder. Every
            ladder starts at 1500, so without a floor the top of the table
            is players who won a handful of matches from the starting
            rating. Echoed back in `meta.coverage.qualified`. REFUSED with
            400 when no requested system is `elo` (2026-09-20); it was
            previously accepted and ignored.
        - name: activity_weeks
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 104, default: 52 }
          description: >-
            `system=elo` listing only. The ladder must have moved within
            this many weeks of `as_of`. Elo does not decay, so without an
            activity window every leaderboard is topped permanently by
            players who have stopped playing. Echoed back in
            `meta.coverage.qualified`. REFUSED with 400 when no requested
            system is `elo` (2026-09-20); it was previously accepted and
            ignored.
        - name: as_of
          in: query
          required: false
          schema: { type: string, format: date }
          description: YYYY-MM-DD. Omit for the latest known record.
        - name: system
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum: [atp, wta, itf_jt, itf_mt, itf_wt, utr, elo, atp_doubles, wta_doubles]
          explode: true
          description: >-
            Restrict to one or more systems. Omit for all of the official
            systems — `elo`, `atp_doubles` and `wta_doubles` are NEVER included
            implicitly and must be named (a doubles tie prints as repeated
            ranks, as the publisher prints it),
            so an existing request's response is unchanged. Naming a system
            your plan does not cover refuses the whole call with 403 rather
            than silently returning the part you are entitled to.
        - { $ref: "#/components/parameters/limit" }
        - { $ref: "#/components/parameters/offset" }
      responses:
        "200":
          description: Ranking records in force at `as_of`
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/RankingRecord" }
                  meta: { $ref: "#/components/schemas/RankingListMeta" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /rally/matches:
    get:
      summary: Charted matches with shot-by-shot data (ULTRA)
      description: >-
        Charted matches, newest first. RALLY CONSTRUCTION IS THE LAYER BELOW
        THE TAPE: the tape says what the score became after each point, this
        says how the point was played.


        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" }
        "410": { $ref: "#/components/responses/MatchGone" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /charting/players:
    get:
      summary: Career shot-level charting aggregate for one player (ULTRA)
      description: >-
        The deepest serve/return profile we hold, from the Match Charting
        Project: serve placement (deuce/ad × wide/body/T), return depth and
        outcomes, net and serve-and-volley conversion, clutch
        break/game/set-point serving and returning, winners and unforced
        errors by wing, and rally-length and shot-direction tendencies —
        summed over the player's charted matches. `name` (min 3 chars) is the
        key; a fragment matching more than one charted person is refused with
        the candidate list, and `gender=men|women` disambiguates. An exact
        name selects its person even where a longer name contains it (same
        rule as `/h2h`), while one name charted under both genders still
        refuses, which is what `gender` is for. Every field
        is a raw SUM over the player's Total rows and `matches_charted` states
        the sample. COVERAGE IS CURATED — 11,803 charted matches across both
        tours back to the 1960s, concentrated on the majors, NOT full-slate
        coverage.
      operationId: getChartingPlayer
      parameters:
        - name: name
          in: query
          required: true
          schema: { type: string, minLength: 3 }
          description: Player name (fragment, min 3 chars).
        - name: gender
          in: query
          required: false
          schema: { type: string, enum: [men, women] }
          description: Disambiguates a fragment that matches one charted person per tour side.
      responses:
        "200":
          description: The player's summed charting families with the sample size
          content:
            application/json:
              schema:
                type: object
                properties:
                  player: { type: object }
                  matches_charted: { type: integer }
                  coverage: { type: string }
                  families:
                    type: object
                    description: Per-family summed numeric columns.
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /charting/matches/{chartingMatchId}:
    get:
      summary: One charted match, every stat family for both players (ULTRA)
      description: >-
        Every Match Charting Project stat family for one charted match, both
        players, with the per-set split (row/set 1, 2, Total) exactly as
        charted. `chartingMatchId` is this product's own id space (1960–2026,
        mostly matches with no counterpart in the live table).
      operationId: getChartingMatch
      parameters:
        - name: chartingMatchId
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: The charted match's stat families, both players, per set
          content:
            application/json:
              schema:
                type: object
                properties:
                  charting_match_id: { type: integer }
                  mcp_id: { type: string }
                  gender: { type: string }
                  players: { type: object }
                  families: { type: object }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /webhooks:
    post:
      summary: Register an outbound webhook (ULTRA, direct keys only)
      description: >-
        We POST the same frames the WebSocket sends to your HTTPS endpoint on
        every live score commit. Up to 3 webhooks per key (`409 webhook_limit`
        past that). The response is the ONLY time the signing secret is shown —
        store it.


        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, status, stoppages] }
                  default: [score]
                  description: >-
                    `score` = every accepted live-score commit; `break_point`
                    = the derived `break_point` / `break_point_result`
                    frames; `point` = one POST per live point (the
                    `PointFrame` shape), where that surface is enabled and
                    the match has `pbp_coverage: "point"`.
      responses:
        "201":
          description: Created — includes `secret` (shown exactly once)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Webhook" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "409":
          description: Webhook limit reached (3 per key) — delete an existing webhook first
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
    get:
      summary: List your webhooks (ULTRA, direct keys only; never includes the secret)
      operationId: listWebhooks
      responses:
        "200":
          description: Your webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Webhook" }
                  meta:
                    type: object
                    properties:
                      count: { type: integer }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /webhooks/{webhookId}:
    delete:
      summary: Remove one of your webhooks (ULTRA, direct keys only)
      operationId: deleteWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted: { type: integer }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /broadcast/match/{matchId}:
    get:
      summary: One flat object for on-air graphics (ULTRA)
      description: >-
        Added 2026-09-24, from a broadcaster's request. ONE flat JSON object
        for one match, built so a graphics template can bind each field to a
        fixed path.


        Three properties make it different from `GET /matches/{matchId}`, and
        each exists because a graphics pipeline breaks without it. The object
        is FLAT — no nested score object, no arrays of arrays. Every key is
        PRESENT on every read: a value we do not hold is `null`, never
        missing, because a missing key breaks a template binding. And the
        score is already in DISPLAY form — `p1_points` reads `"40"` or
        `"AD"`, `set_line` is one string such as `"5-7 2-0"`, and each set has
        its own column — so nothing has to be formatted downstream.


        It is a PROJECTION of what the public API already publishes: the match
        object, its embedded score and the model probability, plus the
        break-, set- and match-point flags derived by the same classifiers the
        scoring pipeline uses. Nothing here is a new fact and nothing is
        guessed.


        BUILT FOR 1 Hz. Every response carries a strong `ETag` and
        `Cache-Control: no-cache, max-age=1`; send `If-None-Match` and an
        unchanged state costs a 304 with no body. ULTRA's burst window is 600
        requests a minute, so ten single-match pollers at 1 Hz fit on one key.
        Detect a new state on `sequence`, not on `served_at`, which changes on
        every read.


        The key may be sent as `Authorization: Bearer <key>`, as `X-API-Key`,
        or as `?token=<key>` for tools that cannot set a header.
      operationId: getBroadcastMatch
      parameters:
        - $ref: "#/components/parameters/matchId"
      responses:
        "200":
          description: The broadcast object for this match
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BroadcastObject" }
        "304": { description: Unchanged since the `ETag` you sent }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /broadcast/live:
    get:
      summary: The broadcast object for every live match (ULTRA)
      description: >-
        The same object as `GET /broadcast/match/{matchId}`, for every
        actively-live match, in one call. A ticker or a multi-match wall polls
        this instead of one URL per match, and it stays ONE request however
        many matches are live. At most 200 objects.


        Same 1 Hz contract, same `ETag` and `Cache-Control`, same display-form
        fields, same every-key-present rule. An empty `data` means nothing is
        live right now and is the ordinary overnight answer, not a fault.
      operationId: getBroadcastLive
      parameters:
        - name: tour
          in: query
          description: Restrict to one tour, same vocabulary as `?tour=` elsewhere.
          schema: { type: string }
      responses:
        "200":
          description: Every live match as a broadcast object
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/BroadcastObject" }
                  count: { type: integer }
                  served_at: { type: string, format: date-time }
        "304": { description: Unchanged since the `ETag` you sent }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /ws-token:
    get:
      summary: Mint a connection token for the high-fan-out push feed (ULTRA)
      description: >-
        Returns a short-lived signed token plus the push WebSocket URL and the
        channel vocabulary: `match:{match_id}` per-match streams and
        `slate:all` for every live score frame. Frames are the same allowlist
        score objects the polling endpoints return. This is a separate surface
        from the native `/ws` feed described above — same ULTRA gate, built
        for high fan-out (no shared connection ceiling), and the recommended
        home for continuous/production streaming.


        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, and since 2026-09-12 the
        stoppage family: `medical_timeout_start/end`, `trainer_called/_end`,
        `toilet_break_start/end`, `stoppage_start/end`, `pause_start/end`). A family absent from
        the response will not deliver for your key right now.
        Deliberately separate channels: a `slate:all` subscriber asked
        for score states and never starts receiving events unasked. Point
        and signal frames are events, not states — a missed point does NOT
        self-correct on the next frame; recover it via
        `GET /matches/{matchId}/points?after_seq=` and dedup by `seq`.


        WITHDRAWN STATES, AND HOW TO GET ONE BACK. This feed publishes every
        state we accept and runs no trust deference, while
        `GET /matches/{matchId}/score` runs the legality gate and can serve an
        older state than the newest row. So a state you receive here can later
        be one we do not stand behind, and when that happens a
        `score_withdrawn` frame follows the state's own `score` frame on the
        same channel. Eight keys, and no replacement score:


        ```json
        { "type": "score_withdrawn", "match_id": 4711, "kind": "withdrawn",
          "superseded_sequence": 118, "reason": "illegal_completed_set",
          "safe_to_resume": true, "ts": "2026-09-25T10:00:03.108Z",
          "published_at": "2026-09-25T10:00:03.115Z" }
        ```


        `superseded_sequence` is the `sequence` you hold and are to discard.
        The state to resume from is the one on the next `score` frame, or on a
        fresh `GET /matches/{matchId}/score`. `kind` is `withdrawn` (discard),
        `deferred` (the refused state may be early and is pending the next
        accept, so hold it) or `withheld` (nothing publishable, `games` is
        null). `ts` is when the judgement was made, `published_at` when this
        feed was handed the frame. A given (match, `sequence`) is withdrawn at
        most once per publishing process and there is no replay.


        A consumer that was disconnected recovers the judgement from the
        durable record, added 2026-09-25:
        `GET /matches?withdrawn_since=<instant>` for the matches that had one,
        `GET /matches/{matchId}/withdrawals` for the whole record on a match
        (each row carrying the frame exactly as it went out, and the
        `sequence` served in the refused state's place), and
        `GET /matches/{matchId}/score?sequence=N` to ask about the one
        sequence you hold. Records are kept 90 days. The live `verdict` on the
        score read is the same judgement on demand, but it is recomputed over
        the newest state, so it stops answering for N as soon as the next
        state is accepted. The record does not.
      operationId: createWsToken
      responses:
        "200":
          description: Connection token, push URL and channel vocabulary
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  expires_in: { type: integer }
                  ws_url:
                    type: string
                    description: The push WebSocket URL to connect to with the token.
                  channels:
                    type: object
                    description: >-
                      Channel vocabulary — `match` is the per-match pattern
                      (`match:{id}`), `slate` is the every-live-score channel
                      (`slate:all`). A channel listed here will actually
                      deliver for your key; one missing will not.
                    properties:
                      match: { type: string }
                      slate: { type: string }
                      point_match:
                        type: string
                        description: >-
                          Per-match point events (`point:match:{match_id}`).
                          Present only when the point feed is enabled
                          server-side and the key's plan carries the point
                          surface.
                      point_slate:
                        type: string
                        description: >-
                          Every point frame (`point:slate`). Present only
                          when the point feed is enabled server-side and the
                          key's plan carries the point surface.
                example:
                  token: "eyJhbGciOi..."
                  expires_in: 3600
                  ws_url: "wss://api.livetennisapi.com/connection/websocket"
                  channels:
                    match: "match:{match_id}"
                    slate: "slate:all"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/UpgradeRequired" }
        "429": { $ref: "#/components/responses/RateLimited" }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Direct API key: Authorization: Bearer <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.
    tournamentId:
      name: tournament_id
      in: query
      required: false
      schema:
        type: string
        pattern: '^[0-9]{1,20}$'
      description: >-
        Filter to one tournament — exact match on the stable numeric id every
        match row publishes as `tournament_id` and `/tournaments` publishes as
        `id`, so the value round-trips straight off any response. Works on
        `/matches` (every status) and `/history/matches`, and composes with
        every other filter: `?tour=atp&draw=singles&tournament_id=1217` is one
        slam's men's singles, where `?tour=` alone still mixes concurrent
        events during a slam fortnight. There is no separate edition or
        occurrence id: `tournament_id` is stable across seasons, so one
        EDITION is `tournament_id` plus a `from`/`to` window around its dates.
        Matches whose `tournament_id` is null (a tournament not yet in the
        catalogue) never match this filter; a date-window listing without it
        still returns them. Unknown-but-numeric ids return an empty list, not
        an error; a non-numeric value is a 400 `bad_tournament_id`.
    tier:
      name: tier
      in: query
      required: false
      schema: { type: string }
      description: >-
        Tier filter (added 2026-09-22): comma-separated exact values from the
        closed tier vocabulary (`?tier=wta_125`,
        `?tier=itf_w35,itf_w50,itf_w75`,
        `?tier=challenger_75,challenger_100`). Selects matches whose `tier`
        field carries one of the values — the level the tournament was played
        at in the MATCH'S season, read from the same per-season table, so
        filter and field cannot disagree. A match whose `tier` is null matches
        no value. Composes with every other filter
        (`?tour=challenger&gender=women&tier=wta_125` and `?tier=wta_125`
        select the same rows; `?tier=challenger_125&draw=doubles` is a slice
        `tour=` alone cannot make). Available on `/matches` (every status) and
        `/history/matches`. `/tournaments` takes `?tier=` as well, reading the
        CURRENT season rather than a match's, and states that difference on its
        own parameter. Unknown value → 400 `bad_tier` with the offending
        values in `bad` and the full vocabulary in `allowed`.
    withdrawnSince:
      name: withdrawn_since
      in: query
      required: false
      schema:
        type: string
      description: >-
        ULTRA. A DIFFERENT LISTING, not a filter on the match page: the match
        ids with a WITHDRAWN score state at or after this instant, newest
        first, one row per match as `{ match_id, withdrawals,
        last_withdrawn_at }` with an exact `meta.total` and `limit` / `offset`
        paging. A UTC date (YYYY-MM-DD) or an ISO-8601 UTC datetime. This is
        how a stream consumer that was disconnected finds which matches to ask
        `GET /matches/{matchId}/withdrawals` about. It takes no other
        parameter beside `limit` and `offset` — `status`, `updated_since`, the
        date range and every match filter are `400 bad_withdrawn_since`, as is
        an unparseable instant. Records are kept 90 days from the withdrawal.
    sequence:
      name: sequence
      in: query
      required: false
      schema:
        type: integer
      description: >-
        The `sequence` YOU HOLD for this match, from the push feed, the
        WebSocket or an earlier read. `verdict` is recomputed on every read
        over the newest state, so on its own it says nothing about a sequence
        that was withdrawn before the next state landed. With `?sequence=N`,
        and only when the read carries no verdict of its own, `verdict`
        answers for N from the durable withdrawal record: `kind: withdrawn`
        with the recorded reason when we discarded that state, null when we
        never did. Only a discarded record is re-asserted this way; a
        `deferred` state may since have been corroborated and a `withheld`
        read described that moment's scan, so neither is. A verdict the read
        produces itself always wins, because it describes the state being
        served. Every other field still describes the served state. A
        non-integer is `400 bad_sequence`, never accepted and ignored.
    updatedSince:
      name: updated_since
      in: query
      required: false
      schema:
        type: string
      description: >-
        CHANGE FEED. A UTC date (YYYY-MM-DD) or ISO-8601 datetime. Returns the
        rows whose `updated_at` is at or after it, OLDEST FIRST, with
        `meta.next_cursor` and `meta.watermark`. Poll from `meta.watermark`,
        not from your own clock — it trails the server by 5s on purpose,
        because a row committed while your request was being served can carry
        a timestamp below your `now` and still not be in your result. Overlap
        ~60s and dedupe by `id`; the feed is at-least-once by design. CANNOT
        be combined with `from`/`to` (400 `bad_updated_since`): those filter
        when a match was PLAYED and sort by play time, this filters when its
        row CHANGED, and a change cursor cannot resume a play-time ordering.
        Not accepted with `status=cancelled` (400 `bad_request`). Anything
        unparseable is a 400, never accepted and ignored. A physically DELETED
        row can never appear in the feed; cancellations, walkovers and
        withdrawals are status CHANGES and do appear.
    cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: >-
        Echo back `meta.next_cursor` to fetch the next page of a change feed.
        Opaque — do not parse it, its contents will change. Supplies both the
        floor and the tie-break position, so it replaces `updated_since` on
        follow-up pages rather than accompanying it.
    hasAnalysis:
      name: has_analysis
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        Return only matches that DO (`true`) or do NOT (`false`) have model analysis, matching the
        `has_analysis` flag each row carries (filter added 2026-09-14, documented here 2026-09-20).
        Omit for both. Anything other than true/false is a 400 `bad_has_analysis`, never a silently
        ignored filter. These are the matches `/matches/{matchId}/analysis` can serve; every other
        id answers 404 `no_analysis`. The misses are structural rather than transient — analysis is
        produced only for a match carrying a mapped market — so a caller polling the unanalysed half
        is asking a question whose answer can never become yes. Filter the slate with this instead.

    hasMarket:
      name: has_market
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        Return only matches that DO (`true`) or do NOT (`false`) have a mapped match-winner market,
        matching the `has_market` flag each row carries (added 2026-09-15). Omit for both. Anything
        other than true/false is a 400 `bad_has_market`, never a silently ignored filter. These are
        the matches `/history/matches/{id}/prices` and `/matches/{id}/prices` can serve; every other
        id answers 404 `no_market`. Measured 2026-09-15: 3,718 of the 9,741 matches completed since
        2026-08-16 (38%) had a price tape.

    isQualifying:
      name: is_qualifying
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        Return only matches in the QUALIFYING draw (`true`) or only those the source states are not
        (`false`), matching the `is_qualifying` flag each row carries (field added 2026-08-12,
        filter added 2026-10-02). Omit for both. Anything other than true/false is a 400
        `bad_is_qualifying`, never a silently ignored filter.

        THIS IS THE ONLY WAY TO SPLIT THE TWO DRAWS, and the reason is in the `is_qualifying` field
        description: the two are routinely carried under ONE tournament name with ONE round
        vocabulary, so `tournament`, `tournament_id`, `round` and `round_code` all read main-draw for
        a qualifying match. Do not filter on the round text.

        THREE-VALUED, so this filter is too: a row whose flag is `null` (no source has ever stated
        it) matches NEITHER value and is returned only when the filter is omitted. `null` is an
        answer, not a `false` — returning it under `is_qualifying=false` would assert "main draw" on
        the strength of nothing. Measured 2026-10-02 over completed matches: the flag is stated on
        98.9% of the last 30 days and 98.3% of 2026 outside the UTR circuit, where it is mostly
        unstated (1,695 of the 1,831 unstated rows in the last 30 days are UTR).

    gender:
      name: gender
      in: query
      required: false
      schema: { type: string, enum: [men, women] }
      description: >-
        Return only men's or only women's matches, matching the `gender` field each row carries
        (added 2026-09-09, documented here 2026-10-02). Omit for both. Anything other than
        men/women is a 400 `bad_gender`, never a silently ignored filter.

        It exists because `?tour=` deliberately collapses: `challenger` is ATP Challenger AND WTA
        125, and `itf` and `juniors` are both sexes — so without this there is no way to ask for
        men's Challenger at all. A row whose `gender` is `null` (mixed doubles, a team tie) matches
        NEITHER value, the same contract as `?draw=` and `?is_qualifying=`.
            bad_points_complete, bad_combination, points_read_disabled, bad_after_seq, bad_has_market, no_market, points_disabled,
    country:
      name: country
      in: query
      required: false
      schema: { type: string, minLength: 3, maxLength: 3 }
      description: >-
        Filter to matches where EITHER participant's `player.country` equals
        this lowercase 3-letter code — the same vocabulary the Player object
        returns (IOC-style codes, e.g. `ned`, `sui`, `gre`; NOT ISO-3166).
        Players with no recorded country never match, so a country filter
        excludes unknown-nationality matches rather than guessing. A value
        that is not 3 letters is a 400 `bad_country`.
  responses:
    BadRequest:
      description: Bad query parameter
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Unauthorized:
      description: Missing, unknown, or disabled credentials
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    UpgradeRequired:
      description: Your tier doesn't unlock this endpoint
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    NotFound:
      description: No such resource, or no data yet
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    MatchGone:
      description: >-
        The match id existed and was merged into another match record (since
        2026-09-05). The body is `MatchMerged`, not `Error`: it carries a
        forwarding address, which is the whole point of answering 410 rather
        than 404.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/MatchMerged" }
    PlayerGone:
      description: >-
        The player id existed and was merged into another player record, or was
        retired with no successor. The body is `PlayerMerged`, not `Error`: it
        carries a forwarding address, which is the whole point of answering 410
        rather than 404. An id that was NEVER issued keeps its 404 — a 410 would
        assert it once existed.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/PlayerMerged" }
    RateLimited:
      description: >-
        Rate limit exceeded (Retry-After header present). Three body shapes,
        told apart by `error` and `scope`: the per-MINUTE limit
        (`rate_limited`, with `upgrade_url`, `tier` and `price` naming the
        next tier up); the per-DAY quota (`rate_limited` with `scope: "day"`,
        `limit_per_day`, and `resets_at` — the absolute ISO instant the daily
        window resets); and `abuse_throttled` with `retry_at_epoch` — a
        24-hour block applied to clients that keep hammering far past their
        cap, which a well-behaved retry loop never sees. Fix the loop rather
        than retrying through it.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
  schemas:
    PlayerNotFound:
      type: object
      description: >-
        The 404 body for /players/{playerId} and its two stoppage aliases.
        `detail` and `see` appear ONLY when the requested id resolves in the
        results-archive person registry — the signpost across the two id
        spaces. They are absent for an id we simply do not hold. The person is
        never named here: the archive is History-gated and this route is not.
      properties:
        error: { type: string, enum: [not_found] }
        detail:
          type: string
          description: Present only when the id is a corpus person id.
        see:
          type: string
          description: >-
            Present only when the id is a corpus person id — the archive lookup
            that reads it, e.g. `/api/public/v1/history/archive/players?id=104925`.
      required: [error]
    MatchMerged:
      type: object
      description: >-
        The 410 GONE body for a match id that was merged into another match
        record. Distinct from `Error` because it carries a forwarding address.
      properties:
        error:
          type: string
          description: Always `merged`.
        merged_into:
          type: [integer, "null"]
          description: >-
            The id that absorbed this one — re-point your records at it. Null
            means the forwarding target is unknown: nothing to forward you to,
            drop the id. On a merge chain this is the END of the chain, never
            an intermediate id that would 410 in turn.
        merged_at:
          type: string
          format: date-time
          description: >-
            When THIS id stopped existing (UTC). On a chain it is the FIRST
            hop — the moment your copy of this id went stale.
        detail:
          type: string
          description: >-
            Human-readable explanation; differs for a merge and for a
            retirement so the two are distinguishable without parsing prose.
    PlayerMerged:
      type: object
      description: >-
        The 410 GONE body for a player id that was merged into another player
        record, or retired outright. Same shape as `MatchMerged` and the same
        reasoning: a redirect would rewrite the identity inside your warehouse
        without you seeing it, so the id is answered rather than forwarded.
      properties:
        error:
          type: string
          description: Always `merged`.
        merged_into:
          type: [integer, "null"]
          description: >-
            The id that absorbed this one — re-point your records at it. Null
            means the player was RETIRED with no successor: nothing to forward
            you to, drop the id. On a merge chain this is the END of the chain,
            never an intermediate id that would 410 in turn.
        merged_at:
          type: string
          format: date-time
          description: >-
            When THIS id stopped existing (UTC). On a chain it is the FIRST
            hop — the moment your copy of this id went stale.
        detail:
          type: string
          description: >-
            Human-readable explanation; differs for a merge and for a
            retirement so the two are distinguishable without parsing prose.
    Error:
      type: object
      properties:
        error:
          type: string
          description: >-
            Stable machine-readable code, e.g. bad_date, bad_coverage,
            bad_sequence, bad_points, bad_points_complete, bad_combination,
            points_read_disabled, bad_after_seq, bad_changed_since,
            bad_restated_since, points_disabled, bad_period,
            bad_year, bad_format, bad_tour, bad_tier, bad_country, ambiguous_name,
            not_charted, not_found, no_analysis, no_market, upgrade_required,
            rate_limited, abuse_throttled.
        detail:
          type: string
          description: Human-readable explanation, when one adds anything.
        allowed:
          type: array
          items: { type: string }
          description: >-
            On a rejected enumerated parameter, the values that would have been
            accepted (e.g. the coverage vocabulary for bad_coverage).
    ListMeta:
      type: object
      properties:
        limit: { type: integer }
        offset: { type: integer }
        count: { type: integer }
        total:
          type: [integer, "null"]
          description: >-
            Size of the whole filtered set. Null when it cannot be counted
            cheaply.
        has_more:
          type: boolean
          description: >-
            More results exist beyond this page. Read this rather than
            comparing count to limit. For a complete enumeration of a filtered
            set, page `offset` forward by `limit` until this is false; on
            `completed`/`cancelled` listings `total` is null and this is the
            only end-of-data signal.
        next_cursor:
          type: [string, "null"]
          description: >-
            Change-feed only (`?updated_since=` / `?cursor=`). Opaque token to
            pass back as `?cursor=`. Null means you are caught up — stop
            paging and switch to polling from `watermark`.
        watermark:
          type: [string, "null"]
          format: date-time
          description: >-
            Change-feed only. The floor to use on your NEXT poll. Deliberately
            trails the server clock by 5s so a row committed during this
            request cannot fall through the gap.
    Score:
      type: object
      description: >-
        One state at one instant. ULTRA adds win_probability_p1 + danger.
        Order and de-duplicate on `sequence`, never on `timestamp`.
      properties:
        sets:
          type: array
          items:
            type: integer
        games:
          type:
          - array
          - 'null'
          description: >-
            [games_p1, games_p2]; each a per-set list. NULL means WITHHELD — we hold no
            state for this match we can stand behind (see `detail`); it never means 0-0,
            and an empty array is never used to mean "unknown".
            A deciding set played as a 10-point MATCH TIEBREAK (super-tiebreak) carries
            the BREAKER's score in its slot WHILE IT IS BEING PLAYED — `[[6,4,10],[4,6,5]]`
            is `6-4 3-6 [10-5]`, not a 10-game set — and `is_tiebreak` is true then. Once
            the breaker is over that set is often published as a one-game `1-0`: take the
            match winner from `sets`, never from the deciding set's games.
          items:
            type: array
            items:
              type: integer
        points:
          type: array
          items:
            type: string
        server:
          type:
          - integer
          - 'null'
          enum:
          - 1
          - 2
          - null
        is_tiebreak:
          type: boolean
          description: >-
            The current game is a tiebreak. On a DECIDING set played as a 10-point match
            tiebreak this is true for the whole set, whose `games` slot holds the breaker.
        win_probability_p1:
          type:
          - number
          - 'null'
        danger:
          type:
          - number
          - 'null'
        win_probability_p1_model:
          type:
          - number
          - 'null'
          description: >-
            ULTRA, since 2026-09-12. The same model read computed WITHOUT the
            market-prior anchor — a probability no market price touched. Equals
            win_probability_p1 on a match the anchor does not apply to, and also
            on some rows of an anchored match (the anchor shifts the pre-match
            hold rates, which enter the engine snapped to a 0.01 grid, so a
            shift smaller than a grid step often solves to an identical value); the per-row test is
            win_probability_p1 != win_probability_p1_model. Null on rows
            stamped before it existed (never back-filled).
        win_probability_meta:
          type:
          - object
          - 'null'
          description: >-
            ULTRA, since 2026-09-12. Our own model-regime identifier
            (`model_version`), the UTC instant the two probabilities were
            generated (`generated_at`), whether the anchor applies to this
            MATCH (`market_anchored` — per match, not per row) and, since
            2026-09-15, whether it moved THIS ROW's win_probability_p1 away
            from the twin (`anchor_effective`). Null on rows stamped before it
            existed.
            SEGREGATING A RECORDED CORPUS — cut on the CLOCK, not on the
            version string. Two changes moved published live probabilities
            before `model_version` reflected them, so split a corpus on
            `generated_at` (or the row's `timestamp`) at these two instants:
            2026-08-18T08:29:28Z, when the over-inclusive deciding-set rule
            for lower-tier singles began (some final sets priced as a
            race-to-ten breaker), and 2026-09-16T07:59:54Z, when the
            draw-based rule replaced it (main-draw singles priced as a full
            set — a move of up to 0.20 on affected deciding-set states).
            `model_version` is NOT a safe discriminator across the second
            boundary: the `+itfdraw-2026-09-16` suffix first appears on rows
            generated 2026-09-17T05:04:25Z, 21 h 04 m AFTER the rule itself
            landed, and in that gap 33,510 states across 351 matches (9,719
            states over 113 matches at the ITF M15/W15/W35 levels the rule
            governs) were computed under the CORRECTED rule while still
            carrying `markov-population-2026-08-23`. Cutting on the version
            string — or on a whole-day boundary — mislabels exactly those
            rows; cutting at 2026-09-16T07:59:54Z does not. Measured against
            production 2026-09-19.
            CORRECTION (2026-09-19): both instants were first published, the
            same day, THREE HOURS LATE — 2026-08-18T11:29:28Z and
            2026-09-16T11:02:00Z — because the switch times were read off a
            column stored in local wall time and labelled UTC. The instants
            above are the corrected UTC ones. If you cut a corpus on either
            of the old values, re-cut: everything in the three hours before
            them is on the wrong side.
            Earlier than that there is no stamp to cut on at all: no row
            generated before 2026-09-12T12:08:17Z carries `model_version` or
            `generated_at`, and the bulk tape packages have no version column,
            so for those the row `timestamp` is the only discriminator.
            The `model_version` on an analysis profile (`ModelProfile`) is a
            different identifier for a different object — the forecast's
            prompt scaffold — and does not apply to score rows.
          properties:
            model_version:
              type: string
              example: markov-population-2026-08-23
              description: >-
                The model regime that produced this row: engine family,
                calibration key scheme and — since 2026-09-17 — every pricing
                rule in force, as a `+…` suffix. It is not a safe cut for a
                recorded corpus across the 2026-09-16 boundary; see this
                object's description for the two instants to segregate on.
            generated_at:
              type:
              - string
              - 'null'
              format: date-time
            market_anchored:
              type: boolean
              description: >-
                The market-prior anchor applies to this match: a two-sided
                pre-match price and a pre-play first score gave the model a
                shift to its pre-match prior. Per match, not per row.
            anchor_effective:
              type:
              - boolean
              - 'null'
              description: >-
                Since 2026-09-15. This row's win_probability_p1 differs from
                win_probability_p1_model, i.e. the anchor moved this value.
                Null when either probability is null.
        timestamp:
          type:
          - string
          - 'null'
          format: date-time
          description: >-
            Our clock, not the court's: stamped in our process when the state was
            accepted (the same step that assigns `sequence`), then refreshed — at
            most every 8 s — while the owning source keeps re-asserting the
            unchanged state, so on a live read it is usually the last-assertion
            instant, not the accept instant. Never an upstream observation time,
            never a source's own clock. NOT an ordering key — use `sequence`; for
            the accept instant use `accepted_at`.
        accepted_at:
          type:
          - string
          - 'null'
          format: date-time
          description: >-
            Since 2026-09-15. The instant we accepted this state (UTC): stamped
            once at insert, never refreshed by a re-assertion — the clock to
            difference a latency study against. Present on live score reads and
            push frames, and since 2026-09-24 on history-tape rows too (this
            description said "absent on history-tape rows" until 2026-09-25,
            which had been wrong since the tape started carrying it — see
            `HistoryTapeRow.accepted_at`). Null on the archive fallback of a
            retention-trimmed completed match.
        sequence:
          type:
          - integer
          - 'null'
          description: >-
            Per-match accept counter for this state: 1, 2, 3, … in the order we
            accepted states for THIS match, gapless within a match — higher is
            later, equal is the same state re-served, and a gap between two reads
            is exactly that many missed updates. On /matches/{matchId}/score it
            moves BACKWARDS in two cases only: we withdrew a state we cannot stand
            behind and re-served the last good one, or the read deferred to a
            strictly higher-trust source's fresh state (about 1% of live reads,
            measured 2026-09-15). On the push feed and the native WebSocket it only
            ever rises. Null on states that predate the counter — never fabricated.
            Present on live score reads AND, since 2026-09-26, on history-tape
            rows too — see `HistoryTapeRow.sequence`. This description said
            "absent on history-tape rows, which are already served in order"
            until then, and the reasoning was the gap: being served in order
            does not let you resolve the `replaced_by_sequence` that
            `GET /matches/{matchId}/withdrawals` hands you, which is a pointer
            AT a counter and not a position in a list. Since 2026-09-24 a set
            completion that
            does not end the match is assigned a sequence only once confirmed
            — the same source keeps presenting the completed set for 10 s or
            more, a source at least as trusted presents it, or the same source
            shows play continuing inside the new set. A live scoring display
            can render the set-ending frame ON set point, before the point is
            decided, and step back when it is not won; the unconfirmed frame is
            now never stored, so no sequence ever carries it and nothing is
            published as provisional. Until a frame is confirmed every surface
            keeps serving the set-point state; one nobody confirms within 120 s
            is discarded. A set completion that ENDS the match is exempt — it
            follows the completion rules instead. Measured over the 30 days to
            2026-09-24 this adds a median 10 s between the point and the
            published set-end, and on a feed that does not re-present states
            the set-end lands with the first point of the next set (90th
            percentile 133 s). It does not cover a set genuinely won and then
            corrected on court, which can still be published and rewound.
        age_seconds:
          type:
          - integer
          - 'null'
          description: >-
            Seconds since the score CONTENT last changed (not since we last polled) —
            it keeps rising between points. Null = change-clock unknown for this row,
            never "fresh". Always null on the archived final that
            `/matches/{matchId}/score` serves for a settled match whose live rows
            were retired (since 2026-09-20): no clock is claimed for a state nobody
            watched.
        stale:
          type: boolean
          description: >-
            Our own staleness verdict on age_seconds for a LIVE match (threshold
            currently 120s). Always false on a completed match: its last state is
            final, not stale.
        observed_age_seconds:
          type:
          - integer
          - 'null'
          description: >-
            Seconds since ANY of our sources last CONFIRMED this state — the insert
            itself, the owning source re-asserting it, or an independent source
            agreeing with it. The "is anyone still watching" clock, next to
            `age_seconds`, the "has anything happened" clock: a long age_seconds
            with a small observed_age_seconds is a changeover or set break, not a
            stall. Null = unknown: no observation clock stored on the row, or
            the archive fallback on a retention-trimmed completed match (where
            age_seconds and sources_count are null too). Absent on history-tape
            rows.
        sources_count:
          type:
          - integer
          - 'null'
          description: >-
            How many DISTINCT sources inserted or independently confirmed this
            match's state in the last 60 seconds (our public source window). A
            count, never a name; it counts sources we accepted a state from or
            that agreed with the stored state, so it can under-count and never
            over-counts. 1 is ordinary; 0 on a live match past a full minute
            means nobody we accepted a state from, or who agreed with the stored
            state, has reported it in the last 60 seconds; 0 on a completed
            match is normal. Null = unknown (a read blip, or the archive
            fallback). Present wherever observed_age_seconds is.
        changing_sources_count:
          type:
          - integer
          - 'null'
          description: >-
            Since 2026-09-24. How many DISTINCT sources CHANGED this match's
            score in the last 300 seconds — sources that inserted a new state,
            counted on the content clock alone. A source re-asserting an
            unchanged state is not counted, which is the difference from
            sources_count: a feed stuck re-sending its last state keeps
            sources_count at 1 for as long as the echo lasts and keeps this at
            0. The window is wider than sources_count's on purpose, because a
            point lands every 30-60 s and a changeover is about 90 s. A
            cross-confirmation is agreement, not a change, so this can read
            below sources_count and never above it. 0 on a live match past
            five minutes means nobody moved the score in that time; 0 on a
            completed match is normal. Null = unknown (a read blip, or the
            archive fallback). A count, never a name. Present wherever
            sources_count is.
        corroborated:
          type:
          - boolean
          - 'null'
          description: >-
            Since 2026-09-24. Has an INDEPENDENT source vouched for THIS EXACT
            state? True when a source other than the one that wrote this state
            has since presented us the same state; false when none has,
            including a brand-new state nobody has had a chance to agree with
            yet. This is the field to gate a SET-END on. The two counts above
            are window measures over the match and say nothing about the state
            in front of you, so a set completion only one source has announced
            can sit beside a perfectly healthy sources_count — and a set-end is
            the one state whose correction changes a result rather than a
            number. EVIDENCE, NOT PROOF: a vouched state can still be
            corrected, so read corroborated_age_seconds beside it and treat a
            vouch that is younger than the state it vouches for as the weaker
            signal it is. When we do take a state back the `sequence` goes down
            and `verdict` says so. Null = unknown (the archive fallback on a
            retention-trimmed completed match, where age_seconds and
            sources_count are null too). A yes/no, never a name. Present
            wherever sources_count is.
        corroborated_age_seconds:
          type:
          - integer
          - 'null'
          description: >-
            Since 2026-09-24. Seconds since that independent vouch. Null when
            corroborated is false (nobody has) or null (unknown). Compare it
            with age_seconds: a vouch OLDER than the state means somebody
            agreed with this state after it was published; a vouch younger than
            the state is one that landed late.
        detail:
          type: string
          description: >-
            Present only when something is withheld — plain-language reason, e.g. a
            null `games` array.
        verdict:
          type:
          - object
          - 'null'
          description: >-
            Why this read is not the newest state we judged (since 2026-09-23).
            Null on an ordinary read. Otherwise the legality gate refused a state
            a stream had already published, and this says which and why.
            `superseded_sequence` is the `sequence` of the refused state, the
            value a stream consumer holds. `reason` is the gate's slug. `kind` is
            `withdrawn` (discard the refused state and resume from the served
            one), `deferred` (it may be early and is pending the next accept) or
            `withheld` (nothing publishable, `games` is null). `safe_to_resume`
            is true exactly when `kind` is `withdrawn`. The push feed, the
            WebSocket and webhooks announce the same judgement as a
            `score_withdrawn` frame naming the same sequence, so a stream
            consumer never has to poll to learn a state was taken back. That
            frame carries `type`, `match_id`, `kind`, `superseded_sequence`,
            `reason`, `safe_to_resume`, `ts` and `published_at`, and no
            replacement score: resume from the next `score` frame or from a
            fresh read. Since 2026-09-25 this field also answers for a
            sequence you name with `?sequence=N`, from the durable record
            served by `GET /matches/{matchId}/withdrawals` — which is how a
            consumer that missed the frame recovers it.
          properties:
            kind:
              type: string
              enum:
              - withdrawn
              - deferred
              - withheld
            superseded_sequence:
              type:
              - integer
              - 'null'
            reason:
              type: string
            safe_to_resume:
              type: boolean
    Incident:
      type: object
      description: >-
        One published data-quality incident. Every field is written as part of
        a release, so the record does not change between releases.
      properties:
        id:
          type: string
          description: Stable slug, e.g. `deciding-set-level-rule-2026-08-18`.
        kind:
          type: string
          description: >-
            The incident's family. Current values are `pricing_rule`,
            `version_stamp`, `field_orientation` and `field_repair`. The live
            list is in `meta.kinds`.
        title:
          type: string
        window_utc:
          type: object
          description: >-
            When the incident applies. Every instant is UTC, and `basis` says
            what the window was read from.
          properties:
            start: { type: string, format: date-time }
            end:
              type:
              - string
              - 'null'
              format: date-time
            basis: { type: string }
        rule_before:
          type: string
        rule_after:
          type: string
        defect:
          type: string
          description: What was wrong, with the measurement behind it.
        affected_surfaces:
          type: array
          description: The endpoints and fields the incident reached.
          items: { type: string }
        how_to_tell:
          type: string
          description: >-
            How to separate an affected row from a clean one, in your own copy
            of the data.
        corrections:
          type: object
          description: >-
            Whether the published values were restated. When `available` is
            false, `detail` says what to do instead.
          properties:
            available: { type: boolean }
            detail: { type: string }
        matches:
          type: object
          description: >-
            Whether a per-match list can be derived exactly. `note` names the
            rows that cannot, and `url` is the export when `derivable` is true.
          properties:
            derivable: { type: boolean }
            note: { type: string }
            url: { type: string }
    PlayerStoppage:
      description: >-
        One row of GET /players/{playerId}/stoppages — an in-match stoppage on one of the
        player's matches, or a match the player did not finish. Stoppage rows carry
        `score_at`, `duration_seconds` and `reason`; outcome rows carry `final_score` when a
        score row exists. Never inferred except `pause` (source_stated false).
      type: object
      properties:
        kind:
          type: string
          enum:
          - medical_timeout
          - trainer_called
          - toilet_break
          - pause
          - stoppage
          - retirement
          - walkover
        at:
          type: string
          format: date-time
          description: UTC instant of the stoppage (the source's own instant) or of the recorded outcome.
        match_id:
          type: integer
        tournament:
          type:
          - string
          - 'null'
        opponent:
          type:
          - object
          - 'null'
          description: The other side of the match; null when unknown.
          properties:
            id:
              type: integer
            name:
              type: string
        score_at:
          type: object
          description: Stoppage rows only — the score at the stoppage.
          properties:
            sets:
              type:
              - array
              - 'null'
              items:
                type: integer
            games:
              type: array
              items:
                type: array
                items:
                  type: integer
            points:
              type:
              - array
              - 'null'
              items:
                type:
                - string
                - 'null'
        final_score:
          type: object
          description: Outcome rows only, when a score row exists — sets and games of the newest score row.
          properties:
            sets:
              type: array
              items:
                type: integer
            games:
              type: array
              items:
                type: array
                items:
                  type: integer
        attribution:
          type: string
          enum:
          - player
          - match
          description: >-
            `player` — the source named this player's side (or the result names them as the
            non-winner); `match` — the source stated the stoppage for the match without a side,
            so the row appears in both players' lists.
        duration_seconds:
          type:
          - integer
          - 'null'
          description: Seconds to the matching end row; null when no end row was recorded and on outcome rows.
        source_stated:
          type: boolean
          description: True when a scorer, umpire, live-scoring state or result stated it; false only on `pause` (clock-inferred).
        reason:
          type: string
          description: Stoppage rows only — the stated reason; `unknown` when only a flag reached us.
    PlayerStoppagesMeta:
      type: object
      properties:
        player_id:
          type: integer
        window:
          type: object
          description: The bounds actually applied, UTC.
          properties:
            since:
              type: string
              format: date-time
            until:
              type: string
              format: date-time
        kinds:
          type: array
          description: The kinds this response was filtered to.
          items:
            type: string
        counts:
          type: object
          description: Per selected kind, the number of rows over the WHOLE window (not the page).
          additionalProperties:
            type: integer
        latest_medical_timeout:
          oneOf:
          - $ref: '#/components/schemas/PlayerStoppage'
          - type: 'null'
          description: The newest medical timeout in the window, whatever the page or kind filter; null when none.
        previous_medical_timeout:
          oneOf:
          - $ref: '#/components/schemas/PlayerStoppage'
          - type: 'null'
          description: The one before it; null when fewer than two.
        record_starts:
          type: object
          description: How far back each family is recorded — read before trusting a long window.
          properties:
            stoppages:
              type: string
              description: '2026-09-12 — no stoppage row exists before this day.'
            outcomes:
              type:
              - string
              - 'null'
              description: Date of the oldest match with a stated winner (the field an outcome row needs).
        note:
          type: string
          description: 'In-match stoppages and match outcomes only; no off-court injury record.'
        limit:
          type: integer
        count:
          type: integer
        has_more:
          type: boolean
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass back as `?before=`; null when the window is exhausted.
    Player:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        tour:
          type: [string, "null"]
          description: >-
            The record's OWN tour, which is NOT the `tour` filter vocabulary.
            It is granular (`juniors_boys`, `juniors_girls`, `challenger_men`)
            where the filter is grouped (`juniors`, `challenger`), and a doubles
            team reports it UPPERCASE (`ATP`) where an individual reports
            lowercase (`atp`). Treat it as an opaque string; do not parse it into
            the filter enum.
        country: { type: [string, "null"] }
        ranking:
          type: [integer, "null"]
          description: >-
            Official singles ranking POSITION (the ordinal: 1, 25, 100) — never
            points, seed, race, UTR, Elo or a doubles rank. Men from the official
            ATP table, women from the WTA table, chosen by the player (a Challenger
            or ITF man who holds an ATP ranking carries it here). Refreshed from
            the standings ahead of each match the player has with us; a player who
            has not played recently keeps their last refreshed position. `null`
            when no ranking is held (doubles teams, most ITF/junior-only players).
            Always the CURRENT record, even on historical matches — use
            `/rankings?as_of=` for the rank in force on a date.
        ranking_points:
          type: [integer, "null"]
          description: Points on the same official table, refreshed with `ranking`.
        ranking_movement: { type: [string, "null"], enum: [up, down, same, null] }
        hand: { type: [string, "null"], enum: [R, L, null] }
        backhand: { type: [integer, "null"], enum: [1, 2, null] }
        birthday: { type: [string, "null"], format: date }
        is_doubles_team: { type: boolean }
        data_completeness:
          type: object
          description: >-
            How much biographical detail is known for this player, so a consumer
            can distinguish "not in the feed" from "not yet fetched" without
            probing. Present on every player in a match payload. Lower tours
            carry far less of it than main tour.
          properties:
            known:
              type: [integer, "null"]
              description: >-
                Fields populated, of `of`. NULL on a doubles team, where
                per-player biography does not apply — distinct from `0`, which
                means the fields apply and none are known. Do not decode this
                into a non-nullable integer.
            of:
              type: [integer, "null"]
              description: Fields considered. NULL on a doubles team, as for `known`.
            missing:
              type: array
              description: Names of the unpopulated fields, e.g. ["backhand", "hand"].
              items: { type: string }
            note:
              type: string
              description: >-
                Present only when the object is not applicable, explaining why
                (e.g. a doubles team).
        stats:
          type: object
          description: Single-player endpoint only
          properties:
            ratings: { type: [object, "null"] }
            ratings_as_of:
              type: [string, "null"]
              format: date
              description: >-
                The date (UTC) the `ratings` block was last refreshed (added
                2026-09-10). The current Elo is refreshed every week from the
                published rating tables; read this before treating a rating
                as this week's. Null when there is no rating.
            season: { type: [array, "null"] }
    Match:
      type: object
      properties:
        id: { type: integer }
        tournament: { type: string }
        tour:
          type: [string, "null"]
          enum: [atp, wta, challenger, itf, juniors, null]
          description: >-
            The tour, in the SAME vocabulary the `tour` query filter accepts —
            both are derived from one registry, so a match selected by
            `?tour=X` always carries that value in `tour`. Null when the feed
            never stated a tour or the event type has no public tour name
            (exhibitions, team and mixed events) — never guessed. Safe to
            group and filter on; never parse the tournament name for this.
        tournament_id:
          type: [string, "null"]
          description: >-
            Stable tournament identity — one id per tournament × event type,
            stable across seasons. Joins `GET /tournaments/{tournamentId}`.
            Null when the tournament is not in the catalogue at all (UTR
            events), and on the small residue of matches discovered through a
            secondary source whose tournament name could not be matched to
            exactly one catalogue edition — never guessed. Measured over
            August 2026 terminal matches: ATP 1 of 531 and WTA 3 of 513 null;
            ITF about 2.5% after the 2026-09-04 backfill (was ~25%); UTR 100%.
            (Edge case — a match mislabelled as qualifying by the
            feed has its id re-pointed to the main-draw tournament when
            detected, so the id can change once, early, in that direction
            only.)
        tier:
          type: [string, "null"]
          enum:
            - grand_slam
            - atp_finals
            - atp_1000
            - atp_500
            - atp_250
            - next_gen_finals
            - united_cup
            - davis_cup
            - olympics
            - laver_cup
            - wta_finals
            - wta_elite_trophy
            - wta_1000
            - wta_500
            - wta_250
            - wta_125
            - bjk_cup
            - challenger_175
            - challenger_125
            - challenger_100
            - challenger_75
            - challenger_50
            - itf_m15
            - itf_m25
            - itf_w15
            - itf_w25
            - itf_w35
            - itf_w40
            - itf_w50
            - itf_w60
            - itf_w75
            - itf_w80
            - itf_w100
            - juniors
            - utr
            - exhibition
            - null
          description: >-
            The level the tournament was played at IN THIS MATCH'S SEASON
            (added 2026-09-22) — the official category as the tour publishes
            it, in a closed vocabulary: `grand_slam`; the ATP levels
            (`atp_finals`, `atp_1000`, `atp_500`, `atp_250`,
            `next_gen_finals`); the WTA levels (`wta_finals`,
            `wta_elite_trophy` — last held 2023 — `wta_1000`, `wta_500`,
            `wta_250`, `wta_125`); the ATP Challenger levels (`challenger_175`
            … `challenger_50`); the ITF World Tennis Tour categories
            (`itf_m15`, `itf_m25`, `itf_w15` … `itf_w100` — the 2023 women's
            categories `itf_w25`/`itf_w40`/`itf_w60`/`itf_w80` are kept as
            printed that season, not mapped onto the 2024 ladder, because the
            level a match was played at is a fact about that season); the
            team events (`united_cup`, `davis_cup` and `bjk_cup` in every
            group and stage, `laver_cup`, `olympics`); `juniors`; `utr`; and
            `exhibition` (no ranking points — Hopman Cup class). Same
            vocabulary as the `?tier=` filter, read from the same per-season
            table, so filter and field cannot disagree. Resolved by the
            MATCH'S season (the calendar year of `scheduled_time`), never
            copied from the tournament row: a tournament keeps one
            `tournament_id` across seasons while its level moves — Dallas was
            `atp_250` in 2023 and 2024 and `atp_500` from 2025, so a 2024
            Dallas match reads `atp_250` and a 2025 one `atp_500` under the
            same id. Coverage of the 2023–2026 seasons was verified event by
            event against the official calendars (99.1% of tournament-seasons
            resolved; the rest are deliberately null — the Asian Games tennis
            event, which no tour lists). A new event may read null for a
            short while after its first match until its tier is resolved.
            Null when nothing we hold names the level — never guessed; null
            is "we do not know", never a level. `category` on `/tournaments`
            is unchanged and remains the coarse class (`challenger`, `itf`,
            `atp_250` …); read this field for the level.
        tier_source:
          type: [string, "null"]
          enum: [calendar, name, wikipedia, resolver, null]
          description: >-
            How `tier` was established (added 2026-09-22): `calendar` = the
            official per-season tour calendar named the level (ATP tour and
            Challenger calendars, the WTA tournament list); `name` = an
            unambiguous name rule (the ITF category is in the event's official
            name — `M25 …`, `W35 …` — team and UTR events are named as such,
            and the Slam junior draws and exhibitions are their own event
            type); `wikipedia` = the season's schedule page, used only where
            the official calendar could not state the level for that season
            (Eastbourne 2023–2025); `resolver` = resolved after the seed
            dataset, by the same rules, from the event's name, tour and dates
            in that season. Null exactly when `tier` is null.
        surface:
          type: [string, "null"]
          enum: [hard, clay, grass, null]
          description: >-
            Court surface. Null where no source states one, never inferred from
            a tournament's usual surface in other seasons. TEAM COMPETITIONS
            (Davis Cup, Billie Jean King Cup, Laver Cup) have no surface at
            tournament level — each tie is played on the surface its host nation
            chose — so the match carries its TIE's surface, taken from the ITF's
            published tie record (venue, indoor/outdoor, surface) and the same
            for every rubber of that tie; `tournament.surface` stays null for
            them. A team-event match is null only when the tie's venue is not
            yet published or the match cannot be matched to a single tie
            (competition, date window and the nations on court must agree).
            The other structural null is UTR events, which are not in the vendor
            tournament catalogue at all and so carry `tournament_id: null` too.
            For every other event a surface that IS known is published on both
            the match and its `tournament`, and the two agree.
        indoor: { type: boolean }
        format: { type: [string, "null"], enum: [BO3, BO5, null] }
        round:
          type: [string, "null"]
          description: >-
            The feed's own free-text round label, verbatim. It is the round
            WITHIN the draw this match belongs to, and the draw is named by
            `is_qualifying` — NOT by this string. A qualifying draw has its
            own semi-final and its own final, so `"Buenos Aires 3 -
            Semi-finals"` with `is_qualifying: true` is the semi-final of the
            QUALIFYING draw, not of the tournament. Read the two fields
            together or not at all. The label also embeds the tournament name
            for most feeds — parse the suffix after the last `" - "`, or
            better, use `round_code`.
        round_code:
          type: [string, "null"]
          enum: [F, SF, QF, R16, R32, R64, R128, RR, BR, Q, Q1, Q2, Q3, Q4, ER, null]
          description: >-
            The round in the archive's controlled vocabulary, normalized from
            the free-text label above (`Q` = qualifying round the feed does
            not number). It matches `/history/archive/matches?round=` exactly.
            Null when the label is unrecognised — never guessed.

            IT IS DRAW-RELATIVE AND CANNOT, BY ITSELF, TELL YOU WHETHER A
            MATCH IS QUALIFYING. A qualifying semi-final carries `SF`, the
            same as a main-draw semi-final; only `Q`/`Q1`..`Q4` appear when
            the feed itself names the round as qualifying, which most feeds
            do not. To branch on main draw vs qualifying, use `round_code`
            AND `is_qualifying` together.
        is_qualifying:
          type: [boolean, "null"]
          description: >-
            Whether this match belongs to the QUALIFYING draw, as the source
            states it — never GUESSED from main-draw round vocabulary or from
            the tournament name. (A round the feed itself spells
            `Qualification Round 1` is the source stating it, and reads
            `true`: a `false` beside such a round is a payload contradicting
            itself, not a main-draw assertion. `Semi-finals` and `Final` are
            main-draw vocabulary and are never read that way.)
            This is the only field that separates a qualifying draw
            from the main draw, and it is load-bearing because the two are
            routinely carried under ONE tournament name with ONE round
            vocabulary: a tournament will publish a dozen `Semi-finals` and
            several `Final` that are all qualifying, a week before the main
            draw begins. Neither `tournament`, `tournament_id` nor
            `round_code` can tell them apart.

            THREE-VALUED, and `null` is NOT `false`. `true`/`false` are the
            source's own assertion; `null` means no source has ever stated
            it — every row written before the field existed, and rows whose
            only feed carries no equivalent field. Treat `null` as unknown
            and filter accordingly, exactly as with every other nullable
            field on this object.
        status:
          type: string
          enum: [upcoming, live, completed, cancelled]
          description: >-
            The settled lifecycle. `completed` is asserted only for a match
            we observed being played or whose match-winner market settled
            decisively (one side paid out) — a closed market alone never
            finishes a match (rule stated 2026-08-23; rows mis-published
            before it were corrected). `cancelled` with `event_status: null`
            means we hold positive evidence the match was not played as
            scheduled (the market settled void) but no vendor word for why —
            `outcome` and the fixture `reason` stay null rather than guessed,
            and the row upgrades to a completed walkover with `winner` /
            `withdrew` if a `Walk Over` with a stated winner lands later. The
            flip `upcoming → cancelled` runs through a gate (well past the
            scheduled time, no play recorded), never inline on a feed flap.
        event_status:
          type: [string, "null"]
          enum: [Finished, Retired, Cancelled, Walk Over, Postponed, Interrupted, Unresolved, null]
          description: >-
            The feed's own designator for the match state, passed through
            verbatim. `Finished` is by far the most common value — 144,266 of
            the 150,678 rows carrying one at 2026-09-18 — and until this
            version it was missing from this enum, so a strictly-validating
            generated client rejected the majority of completed matches. It is
            listed now, with `Unresolved` (every source lost the match before a
            result; see `outcome`). The rest name a match that did not run its
            course: retirement, cancellation, walkover, postponement, or an
            in-play suspension (`Interrupted` — rain/darkness/medical; the
            match is paused, not over). NULL does NOT mean "completed
            normally": it means the feed never stated anything for this match,
            which covers matches that ran their course and matches nothing was
            ever said about alike. `event_status: Finished` while `status` is
            still `live` is not a contradiction — one source has called the
            match over and we have not yet confirmed the final, so the score
            may stand still until we do (`stale` goes true, `age_seconds`
            climbs). Measured over the seven days to 2026-09-18, across 649
            matches, that gap closed in 111 s at the median and 911 s at the
            ninetieth percentile; 85 ran past ten minutes. Two honest caveats:
            the value is cleared if a suspended match resumes (no record of the
            pause survives), and for `Retired`/`Walk Over` the withdrawing
            player is reported in `withdrew`, where derivable.
        event_status_updated_at:
          type: [string, "null"]
          format: date-time
          description: >-
            When `event_status` last CHANGED, UTC (ISO-8601, `Z`) — added
            2026-08-19. The instant WE recorded the walkover / retirement /
            cancellation / postponement / suspension (or its clearing), not
            when the tournament desk or the feed did: this is the field to
            measure our admin-status latency with. Bumps only on a change of
            value (a re-read of the same status never moves it; a clear back
            to null does). Null while `event_status` has never changed since
            the field was introduced (2026-08-19) — never backfilled, never
            guessed.
        is_doubles:
          type: boolean
          description: >-
            Doubles match — kept for compatibility, and LOSSY. Evidence order:
            a doubles-team participant proves true regardless of the event
            type; otherwise the feed's event type decides. The loss: false
            also covers "unknown" — a match with no stated event type and no
            team participant reads false here, which is not a claim of
            singles. Prefer `draw`, whose null says so honestly.
        draw:
          type: [string, "null"]
          enum: [singles, doubles, null]
          description: >-
            The honest THREE-VALUED draw (added 2026-08-18) — same vocabulary
            as the `?draw=` filter, decided by the same shared definition, so
            filter and field cannot disagree. Evidence order as is_doubles: a
            doubles-team participant proves doubles over any event type;
            otherwise the feed's event type decides. Null means neither says
            anything — the feed stated no event type, or the match is part of
            a team tie (Davis Cup / BJK Cup / United Cup class), where one
            event type covers both singles and doubles rubbers and we will not
            guess which this is. Null is NOT singles.
        scheduled_time: { type: [string, "null"], format: date-time }
        live_at:
          type: [string, "null"]
          format: date-time
          description: >-
            The instant our feed last reported the match in play (UTC), added
            2026-09-09 — the closest thing to an actual start time; a match that
            starts late has this well after `scheduled_time`, one that starts
            early has it before. Null for matches that went live before
            2026-09-05 (when the stamp began) or were never observed live;
            re-stamped if a match is demoted and promoted again.
        result_restated_at:
          type: [string, "null"]
          format: date-time
          description: >-
            When the published result of this match was LAST corrected (UTC),
            added 2026-09-22 — the instant of the newest `restatement` row on
            `GET /matches/{matchId}/status-history`. A correction is any
            change to `status`, `event_status`, `winner` or the final score
            (sets, games) after the match was first published as completed
            (or as a cancelled walkover with a winner). Null when the result
            stands as first published. Present on every match surface. Poll
            `GET /history/matches?restated_since=` to find corrections.
        result_version:
          type: integer
          description: >-
            `1` plus the number of corrections to the published result (added
            2026-09-22). `1` = the result stands as first published; each
            `restatement` row on the status history adds one. Record it with
            the result you settle on and compare on re-read — a higher number
            means the result you hold was superseded, and the status history
            says what changed.
        players:
          type: object
          properties:
            p1: { $ref: "#/components/schemas/Player" }
            p2: { $ref: "#/components/schemas/Player" }
        score:
          oneOf:
            - { $ref: "#/components/schemas/Score" }
            - { type: "null" }
        winner:
          type: [integer, "null"]
          description: >-
            Completed matches only — derived from final sets. Served for the
            full archive age: a match older than the live-table window reads
            its final state from the same store the tape serves, so old
            completed matches carry a winner too.
        outcome:
          type: [string, "null"]
          enum: [completed, retired, walkover, default, abandoned, unresolved, null]
          description: >-
            The settlement outcome (added 2026-08-18), one closed vocabulary
            derived from `status` + `event_status` so the two can never
            disagree: `completed` = ran its full course; `retired` = a player
            retired in play; `walkover` = conceded before a ball was struck;
            `default` = a player was defaulted; `abandoned` = called off
            unfinished with no result awarded; `unresolved` (added 2026-09-10)
            = every source lost the match before a result and it was closed
            unfinished — `score` is the last state we observed, `winner` is
            null and no result is asserted; it flips to `completed` with the
            proven final when an authority confirms the result. NULL while the
            match is upcoming/live and on a cancelled fixture that never
            produced a result — null is not `completed`. Branch settlement on
            this field, never on `event_status` spellings. New values may be
            added within v1; handle unknowns gracefully.
        withdrew:
          type: [integer, "null"]
          description: >-
            Completed matches only — which player retired or conceded the
            walkover (1|2). Present only when `event_status` is
            `Retired`/`Walk Over` and the winner is derivable; the withdrawer
            is the loser by the rules of the sport. Absent means "not a
            withdrawal, or no evidence" — never a guess.
        has_analysis:
          type: boolean
          description: >-
            Whether a model thesis or profile exists for this match — on every
            list row and the detail, every tier (since 2026-09-02). Filter the
            slate on this before calling `/matches/{matchId}/analysis`, which
            answers `404 no_analysis` about the same fact.
        has_market:
          type: boolean
          description: >-
            Whether a match-winner market is mapped to this match (every tier,
            since 2026-09-02). Same role for `/markets/{matchId}/prices`
            (`404 no_market`).
    MatchDetail:
      allOf:
        - { $ref: "#/components/schemas/Match" }
        - type: object
          properties:
            analysis:
              $ref: "#/components/schemas/Analysis"
              description: ULTRA only (absent below)
            market:
              oneOf:
                - { $ref: "#/components/schemas/Market" }
                - { type: "null" }
              description: PRO+ only (absent below)
    Analysis:
      type: object
      properties:
        thesis:
          type: [object, "null"]
          properties:
            pick_side: { type: integer, enum: [1, 2] }
            confidence: { type: [number, "null"] }
            win_probability_pick: { type: [number, "null"] }
            state: { type: [string, "null"], enum: [valid, confirmed, weakened, broken, null] }
            reasoning: { type: [string, "null"] }
            notes:
              type: object
              properties:
                matchup: { type: [string, "null"] }
                environment: { type: [string, "null"] }
                fatigue: { type: [string, "null"] }
            scenario_playbook: { type: [array, "null"] }
            created_at: { type: [string, "null"], format: date-time }
        profile:
          type: [object, "null"]
          properties:
            win_probability_p1: { type: [number, "null"] }
            expected_closeness: { type: [number, "null"] }
            volatility_rating: { type: [string, "null"], enum: [low, med, high, null] }
            stage:
              type: [string, "null"]
              enum: [pregame, live, null]
              description: >-
                Did this forecast already see the match? null = UNKNOWN, never
                pregame.
            model_version:
              type: [string, "null"]
              description: >-
                The prompt-scaffold version this forecast was produced under,
                so a forecast can be evaluated against the framing that
                produced it and a scaffold change reads as a regime break
                rather than unexplained drift. Null on profiles written before
                the stamp existed.
            input_state:
              type: [object, "null"]
              description: >-
                For an in-play forecast (stage=live), the score it was actually
                looking at, so it can be evaluated against the position rather
                than only excluded. Null on a pregame profile (it saw no score)
                and null wherever the state could not be established. NOT
                reconstructed from the score at created_at — that timestamp is
                written after the model finishes, so it lands later than what
                the model saw.
              properties:
                capture:
                  type: string
                  enum: [writer, recovered]
                  description: >-
                    writer = stamped as the forecast was produced, from the
                    score row itself (carries live_score_id and stats).
                    recovered = reconstructed from the stored prompt text of
                    that same forecast; the score is exact but there is no
                    live_score_id and no stats.
                live_score_id: { type: [integer, "null"] }
                total_games: { type: [integer, "null"] }
                score:
                  type: [object, "null"]
                  description: >-
                    server is the serving SIDE (1 or 2); on doubles that is the
                    team, not the individual.
                  properties:
                    sets: { type: [array, "null"], items: { type: integer } }
                    games: { type: [array, "null"] }
                    points: { type: [array, "null"] }
                    server: { type: [integer, "null"] }
                    is_tiebreak: { type: [boolean, "null"] }
                    timestamp: { type: [string, "null"], format: date-time }
                stats: { type: [object, "null"] }
            key_factors: { type: [array, "null"], items: { type: string } }
            created_at: { type: [string, "null"], format: date-time }
    Market:
      type: object
      properties:
        id: { type: integer }
        question: { type: [string, "null"] }
        status: { type: [string, "null"], enum: [active, resolved, closed, null] }
        volume: { type: [number, "null"] }
        liquidity: { type: [number, "null"] }
        end_date: { type: [string, "null"], format: date-time }
        prices:
          type: array
          description: Prices endpoint / match detail only; newest first
          items: { $ref: "#/components/schemas/Price" }
    Price:
      type: object
      description: >-
        Prediction-market top-of-book quote (probability-like, [0,1]); reflects
        market trading, not an official line, and can lag live scores. Tagged
        so a synthesised quote is never mistaken for a live book.
      properties:
        side:
          type: [integer, "null"]
          description: >-
            1 = players.p1's outcome, 2 = players.p2's - decided by our name-verified
            match-market mapping, never by the venue's own display order (the venue lists
            roughly half of all pairings the other way round). Fixed 2026-09-09: ticks served
            before that date followed the venue's display order, so on those markets side was
            reversed; the mapping is stored, so re-reading any tick now returns the correct side.
        bid: { type: [number, "null"] }
        ask: { type: [number, "null"] }
        mid:
          type: [number, "null"]
          description: >-
            The venue's observed midpoint at the instant we polled or streamed it - never a
            model estimate. Only mid is always real; see synthetic.
        spread: { type: [number, "null"] }
        price_source:
          type: [string, "null"]
          description: Feed category, e.g. prediction_market
        synthetic:
          type: [boolean, "null"]
          description: >-
            true = bid/ask are estimated from mid (mid +/- 0.005, not a live order book) -
            mid itself is the venue's observed midpoint, never a model estimate;
            false = real top-of-book from the live order-book stream;
            null = unknown (older ticks). The live stream attaches when a match goes
            live, so pre-match ticks are synthetic: true by design.
        timestamp:
          type: [string, "null"]
          format: date-time
          description: >-
            When we observed this quote (UTC) - our observation clock, not a venue
            publication time.
    PointPrice:
      type: object
      description: >-
        One played point with the match-winner quote in force per side when it was captured
        (added 2026-09-15). The score state is the BASIC tape's; the ULTRA-only per-point fields
        (server, winner, serve, outcome) are not here. Prices are keyed by neutral side and carry
        no venue or token identifiers.
      properties:
        seq:
          type: integer
          description: Per-match monotonic position 1..N — the same seq as the live points row.
        at:
          type: string
          format: date-time
          description: Our capture time of the point (UTC).
        sets:
          type: array
          items:
            type: integer
        games:
          type: array
          description: Per-set games arrays, [p1, p2].
          items:
            type: array
            items:
              type: integer
        score:
          type: object
          properties:
            p1:
              type:
              - string
              - 'null'
            p2:
              type:
              - string
              - 'null'
        tiebreak:
          type: boolean
        prices:
          type: object
          description: Keyed by side — "1" = players.p1's outcome, "2" = players.p2's.
          properties:
            '1':
              type:
              - object
              - 'null'
              description: The quote for this side, or null when no usable quote exists for the point.
              properties:
                bid:
                  type:
                  - number
                  - 'null'
                ask:
                  type:
                  - number
                  - 'null'
                mid:
                  type:
                  - number
                  - 'null'
                spread:
                  type:
                  - number
                  - 'null'
            '2':
              type:
              - object
              - 'null'
              description: The quote for this side, or null when no usable quote exists for the point.
              properties:
                bid:
                  type:
                  - number
                  - 'null'
                ask:
                  type:
                  - number
                  - 'null'
                mid:
                  type:
                  - number
                  - 'null'
                spread:
                  type:
                  - number
                  - 'null'
        lag_seconds:
          type:
          - integer
          - 'null'
          description: Seconds between the quote and the point, the larger of the two sides (a
            negative side lag means the first quote after the point was used); null when no side
            aligned.
        resolution:
          type:
          - string
          - 'null'
          enum:
          - tick
          - minute
          - coarse
          - null
          description: tick |lag| <= 15 s, minute <= 90 s, coarse beyond — the coarser of the two
            sides; null when no side aligned. An honest label, never upgraded.
    SlateEvent:
      description: An Event as served by the slate-wide feed (GET /events) — the per-match row plus its id and match.
      allOf:
        - $ref: "#/components/schemas/Event"
        - type: object
          properties:
            id: { type: integer, description: "The event's id; the `after_id` cursor." }
            match_id: { type: integer }
    Event:
      type: object
      properties:
        type:
          type: string
          enum: [break, set_won, game_won, momentum_run, stoppage_start, stoppage_end,
                 pause_start, pause_end, medical_timeout_start, medical_timeout_end,
                 trainer_called, trainer_called_end, toilet_break_start, toilet_break_end]
          description: >-
            The stoppage family (added 2026-09-12). `medical_timeout_start/end`,
            `trainer_called/_end` and `toilet_break_start/end` are stated by the
            match scorer or chair umpire, with `player` = the player concerned.
            Coverage (2026-09-13): WTA, WTA 125, Challenger and UTR singles — WTA and
            WTA 125 from the umpire console in two layers: the match state within
            ~20 s (`trainer_called`, `toilet_break_*`, `stoppage_*`, player null) and
            the console's event feed, published by the tour with a variable delay
            (measured 2026-09-13: about one minute to an hour behind play), which adds `medical_timeout_start/end` with
            the player and exact instants; Challenger and UTR from the scorer
            timeline (22 of 70 finished Challenger matches, median 8 s).
            ITF World Tennis Tour singles from the court's live-scoring state
            (the state, not the player: `player` is null on ITF rows; first
            medical timeout observed and published 2026-09-13). ATP main tour:
            a public live-score service's match stage is watched for its
            medical-timeout and interruption stages — present in its
            vocabulary, not yet observed on a tennis match, so ATP rows are
            mapped, not yet proven (`player` null, `at` = our observation
            instant). Not doubles. `stoppage_start/end` is a
            whole-match stop (`reason` weather | other when stated, unknown when
            only a bare suspension flag reached us). `pause_start/end` is an
            interruption of play measured from our own point clocks
            (`basis: inferred`), never labelled medical.
        player: { type: [integer, "null"], enum: [1, 2, null] }
        timestamp: { type: [string, "null"], format: date-time }
        at:
          type: [string, "null"]
          format: date-time
          description: >-
            Stoppage family — the UTC instant the stoppage happened (for a pause,
            its last score change).
        detected_at:
          type: [string, "null"]
          format: date-time
          description: >-
            Stoppage family — when we recorded it.
        basis:
          type: [string, "null"]
          enum: [observed, inferred, null]
          description: >-
            Stoppage family — observed (a source stated it) or inferred (measured
            from our clocks).
        reason:
          type: [string, "null"]
          description: >-
            Stoppage family — medical_timeout | unspecified | no_treatment | taping |
            changeover_treatment | evaluating | failed | toilet_break | weather | other |
            resumed | unknown.
        position:
          type: [string, "null"]
          enum: [point, changeover, setbreak, null]
          description: >-
            pause rows only — where the last point left the match, which sets the
            silence threshold.
        score:
          type: [object, "null"]
          description: >-
            Stoppage family — sets, games, points, server at the moment of the stoppage.
        duration_seconds:
          type: [integer, "null"]
          description: end rows only.
    BroadcastObject:
      type: object
      description: >-
        One flat object for a live-graphics template. EVERY key below is
        present on every read; a value we do not hold is `null` rather than
        absent, because a missing key breaks a template binding. Points and
        the set line are already in display form.
      properties:
        match_id: { type: integer }
        status: { type: string, description: "`live`, `completed`, `upcoming`" }
        event_status: { type: [string, "null"], description: "The terminal badge where one is stated (`Finished`, `Retired`, `Walk Over`, `Interrupted`); null on a normal live row." }
        outcome: { type: [string, "null"] }
        winner: { type: [integer, "null"], description: "1 or 2, null until a result is established." }
        tour: { type: [string, "null"] }
        tournament: { type: [string, "null"] }
        round: { type: [string, "null"] }
        surface: { type: [string, "null"] }
        best_of: { type: [integer, "null"] }
        is_doubles: { type: boolean }
        p1_id: { type: [integer, "null"] }
        p1_name: { type: [string, "null"] }
        p1_short: { type: [string, "null"], description: "Display short form, `\"J. Sinner\"`. A doubles team keeps each side's last token." }
        p1_country: { type: [string, "null"], description: "Three-letter code." }
        p1_ranking: { type: [integer, "null"] }
        p2_id: { type: [integer, "null"] }
        p2_name: { type: [string, "null"] }
        p2_short: { type: [string, "null"] }
        p2_country: { type: [string, "null"] }
        p2_ranking: { type: [integer, "null"] }
        p1_sets: { type: [integer, "null"] }
        p2_sets: { type: [integer, "null"] }
        p1_games: { type: [integer, "null"], description: "Games in the set in play." }
        p2_games: { type: [integer, "null"] }
        p1_points: { type: [string, "null"], description: "As printed: `\"0\"`, `\"15\"`, `\"30\"`, `\"40\"`, `\"AD\"`, or the tiebreak count." }
        p2_points: { type: [string, "null"] }
        p1_set1: { type: [integer, "null"], description: "Per-set columns. A set not yet played is null on both sides." }
        p2_set1: { type: [integer, "null"] }
        p1_set2: { type: [integer, "null"] }
        p2_set2: { type: [integer, "null"] }
        p1_set3: { type: [integer, "null"] }
        p2_set3: { type: [integer, "null"] }
        p1_set4: { type: [integer, "null"] }
        p2_set4: { type: [integer, "null"] }
        p1_set5: { type: [integer, "null"] }
        p2_set5: { type: [integer, "null"] }
        set_line: { type: [string, "null"], description: "The completed and in-play sets as one string, `\"5-7 2-0\"`." }
        current_set: { type: [integer, "null"] }
        is_tiebreak: { type: boolean }
        match_tiebreak: { type: boolean, description: "True while a deciding match tiebreak is in play." }
        server: { type: [integer, "null"], description: "1 or 2." }
        p1_serving: { type: [boolean, "null"] }
        p2_serving: { type: [boolean, "null"] }
        break_point_for: { type: [integer, "null"], description: "1, 2 or null. Cue an animation on the transition to non-null." }
        set_point_for: { type: [integer, "null"] }
        match_point_for: { type: [integer, "null"] }
        p1_win_pct: { type: [integer, "null"], description: "The model probability as a whole percent. Null where no model figure was computed for this state — never guessed." }
        p2_win_pct: { type: [integer, "null"] }
        sequence: { type: [integer, "null"], description: "The per-match accept counter. THIS is how a poller detects a new state." }
        updated_at: { type: [string, "null"], format: date-time }
        age_seconds: { type: [integer, "null"], description: "Seconds since the score CONTENT last changed." }
        stale: { type: [boolean, "null"], description: "A live match whose content has frozen past the threshold." }
        served_at: { type: string, format: date-time, description: "When this response was built. Changes on every read — do not use it to detect a new state." }
    ScoreWithdrawal:
      type: object
      description: >-
        One withdrawn score state on a match (added 2026-09-25), from the
        durable record behind `GET /matches/{matchId}/withdrawals`.
      properties:
        sequence:
          type: integer
          description: >-
            The refused state's `sequence` — the value you hold from the feed,
            and the frame's `superseded_sequence`.
        kind:
          type: string
          enum:
          - withdrawn
          - deferred
          - withheld
          description: The frame's `kind`. Only `withdrawn` means discard and resume.
        reason:
          type: string
          description: The legality gate's slug, the same value the frame carries.
        published_at:
          type:
          - string
          - 'null'
          format: date-time
          description: >-
            When the refused state's OWN `score` frame was handed to the push
            feed. Null when that state never went out on the feed — the
            judgement was still made and the REST read served it.
        withdrawn_at:
          type: string
          format: date-time
          description: When the judgement was made. The frame's `ts`.
        replaced_by_sequence:
          type:
          - integer
          - 'null'
          description: >-
            The `sequence` of the state served in the refused one's place, the
            newest legal state at that moment. Null on `withheld`, where
            nothing within the scan was publishable. It is on the record and
            NOT on the frame.
        frame:
          type: object
          description: >-
            The `score_withdrawn` frame exactly as the push feed, the native
            WebSocket and webhooks sent it, stamped once so the stored copy is
            the wire copy. Its keys are `type`, `match_id`, `kind`,
            `superseded_sequence`, `reason`, `safe_to_resume`, `ts` and
            `published_at`. It carries NO replacement score and no new
            sequence: the state to resume from is the one on the next `score`
            frame, or on a fresh `GET /matches/{matchId}/score`.
    StatusChange:
      type: object
      description: One row of the per-match status ledger (added 2026-09-12).
      properties:
        at: { type: string, format: date-time, description: The instant we published the change (UTC). }
        status:
          type: object
          properties:
            from: { type: [string, "null"] }
            to: { type: [string, "null"] }
        event_status:
          type: object
          properties:
            from: { type: [string, "null"] }
            to: { type: [string, "null"] }
        outcome:
          type: [string, "null"]
          description: Derived from the after-state by the Match.outcome definition.
        basis:
          type: string
          enum: [observed, backfill, restatement]
          description: >-
            How the row was made. observed = written at the instant of the change (from
            2026-09-11T22:45:48Z);
            backfill = reconstructed on 2026-09-12 from the one stamp per kind the match
            row kept before the ledger existed (last promotion to live from 2026-09-05,
            completion instant from 2026-08-21, last reopen, last event_status change).
            One row per stamp; overwritten intermediate transitions are not recovered.
            restatement (added 2026-09-22) = a CORRECTION to a result that had already
            been published — the match's `status`, `event_status`, winner or final score
            (sets, games) changed after it was first published as completed (or as a
            cancelled walkover with a winner). A correction is always a new row, never an
            edit, written at the instant we made the change; `status` / `event_status`
            carry before and after as usual (the same value twice when only the winner or
            the score moved) and its `score` is the result AFTER the correction (null when
            the match holds no score row, as on a walkover). Every path that can change a
            result writes one — a source's late final, a second authority's correction, an
            operator's repair, a completion reopened and re-closed — because it is enforced
            where the result is written. A re-assertion of the same result, or a change to
            points alone, is not a correction and writes nothing. `result_restated_at` and
            `result_version` on the Match summarise these rows. Rows with this basis exist
            from 2026-09-22; earlier corrections were not signalled.
        score:
          type: [object, "null"]
          description: The newest score row at that instant (sets, games, points, server); null when none existed.
    Fixture:
      type: object
      properties:
        id: { type: integer }
        event_date: { type: [string, "null"], format: date }
        start_time:
          type: [string, "null"]
          format: date-time
          description: >-
            Scheduled start (UTC). Null until the order of play assigns a
            time — a date-only fixture is a real state, and rows written
            before 2026-08-03 stay null.
        player1_id:
          type: [integer, "null"]
          description: >-
            Our player id, when the participant is in our roster (exact-key
            resolution, never a name match). Null otherwise — names are
            always present regardless.
        player2_id:
          type: [integer, "null"]
          description: As `player1_id`, for the second participant.
        tour:
          type: [string, "null"]
          description: >-
            The record's OWN tour, which is NOT the `tour` filter vocabulary.
            It is granular (`juniors_boys`, `juniors_girls`, `challenger_men`)
            where the filter is grouped (`juniors`, `challenger`), and a doubles
            team reports it UPPERCASE (`ATP`) where an individual reports
            lowercase (`atp`). Treat it as an opaque string; do not parse it into
            the filter enum.
        tournament: { type: [string, "null"] }
        round: { type: [string, "null"] }
        round_code:
          type: [string, "null"]
          enum: [F, SF, QF, R16, R32, R64, R128, RR, BR, Q, Q1, Q2, Q3, Q4, ER, null]
          description: >-
            Normalized round — same vocabulary as `Match.round_code`. Null
            when the label is unrecognised, never guessed.
        surface: { type: [string, "null"] }
        player1_name: { type: [string, "null"] }
        player2_name: { type: [string, "null"] }
        status: { type: [string, "null"] }
    ModelProfile:
      type: object
      description: >-
        One model win-probability profile. On the history tape these are the
        profiles produced during the match, oldest first.
      properties:
        win_probability_p1: { type: [number, "null"] }
        expected_closeness: { type: [number, "null"] }
        volatility_rating: { type: [string, "null"], enum: [low, med, high, null] }
        stage:
          type: [string, "null"]
          enum: [pregame, live, null]
          description: >-
            Did this forecast already see the match? null = UNKNOWN, never
            pregame.
        model_version:
          type: [string, "null"]
          description: >-
            The prompt-scaffold version this forecast was produced under. Null
            on profiles written before the stamp existed.
        key_factors: { type: [array, "null"], items: { type: string } }
        created_at: { type: [string, "null"], format: date-time }
    HistoryTapeRow:
      type: object
      description: >-
        One row of the score sequence. Rows we watched live carry a real
        `timestamp`. Rows expanded after the fact from a finished-match
        point-by-point record carry a null `timestamp` AND null model fields,
        because neither a wall clock nor a model output ever existed for them —
        nothing is synthesised. `origin` (since 2026-09-20) says explicitly
        which kind each row is, read from the row's stored provenance — never
        inferred from its clock; a null `timestamp` remains true of every
        reconstructed row. The model fields alone are not a marker, since they
        are stamped best-effort and an observed row may lack them.
        `meta.point_source` / `meta.coverage` say which kind of tape you are
        holding. `origin`, `serve` and `outcome` are present on
        `GET /history/matches/{matchId}` rows; the pre-2023 ArchiveTape (every
        row reconstructed) does not carry them. `winner` (since 2026-09-22) is
        present on EVERY row of every sequence, on both — who won the point
        that produced the row, judged from the score step and from nothing
        else; `server`, `serve` and `winner` together are the three per-point
        facts a model needs, and the third was only implicit in the score
        step before. Reconstructed rows are never
        repaired or reordered: a game whose vendor point record is internally
        inconsistent is withheld whole, not fitted or patched into a legal
        sequence — see `meta.points.games_withheld` (added 2026-09-20).
      properties:
        origin:
          type: string
          enum:
          - observed
          - reconstructed
          description: >-
            `observed` — a row our own pipeline committed while the point was
            being played; `reconstructed` — a row expanded after the fact from
            a finished-match point-by-point record (null timestamp, null model
            fields). From the stored provenance, never inferred from a null
            timestamp. Added 2026-09-20.
        serve:
          type:
          - integer
          - 'null'
          enum:
          - 1
          - 2
          - null
          description: >-
            The serve the point was played on (1 first, 2 second), joined from
            this match's per-point stream: paired by EXACT score state — set
            count, every set's games, in-game points and tiebreak flag all
            equal — and, where a state recurs (a deuce cycle), by nearest
            clock within 90 seconds (the tape row's observed clock against
            the stream point's), each stream point used at most once;
            otherwise null. Observed rows only: null on every reconstructed
            row, on a row no stream point matches, and on a recurring state
            with no clock within the window or two at the same distance.
            Never inferred from the score or the pattern of play. Added
            2026-09-20; clock pairing 2026-09-21.
        outcome:
          type:
          - string
          - 'null'
          enum:
          - ace
          - double_fault
          - winner
          - forced_error
          - unforced_error
          - null
          description: >-
            How the point ended, as an outside source states it — same join
            rule and same nulls as `serve`. `meta.enrichment` says what landed
            on this tape. Added 2026-09-20.
        sets:
          type: array
          items: { type: integer }
        games:
          type: array
          items:
            type: array
            items: { type: integer }
        points:
          type: array
          description: >-
            In-game points as tennis strings ("0", "15", "30", "40", "AD") —
            EXCEPT during a tiebreak, where they are the running tiebreak
            count as plain integer strings ("0", "1", "2", …); `is_tiebreak`
            tells the two notations apart.
          items: { type: string }
        server:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            Who is serving — null where the feed never asserted it. On
            `?sequence=clean` the server is SETTLED per non-tiebreak game
            (the server is physically constant within a game, so the game's
            majority assertion fills nulls and corrects transient
            disagreements; a tie settles nothing). The raw sequence carries
            every row exactly as committed, so a transient wrong-server read
            can appear there and be corrected by a later row.
            TIEBREAK ROWS ARE NEVER SETTLED, on either sequence: the server
            genuinely changes during a breaker, so there is no constant to take
            a majority of, and the field is the source's own assertion carried
            through. Two consequences, both reported by a Basic customer on
            2026-09-25 and confirmed in the code. The rotation cannot be
            reconstructed from the rows served wherever the tape is sampled —
            a breaker whose rows skip points gives you the server of a state,
            not of a numbered point, and `meta.points.transitions_legal`
            against `transitions_total` tells you whether that happened. And
            on the set roll-up row that carries `tiebreak_final`, `server` is
            the value of that committed set-end state: it is NOT a preserved
            copy of the final breaker point's server, and we make no claim
            that it is. Withhold server-dependent tiebreak analysis unless the
            encoding reconciles on the match in front of you.
        is_tiebreak: { type: boolean }
        tiebreak_final:
          type:
          - array
          - 'null'
          description: >-
            Added 2026-09-24. The breaker's closing score in our player order,
            e.g. `[2, 7]`, on the row that CLOSES a tiebreak set. Absent on
            every other row, including the breaker rows themselves, which stay
            exactly as they were observed. Same value, from the same resolver,
            as this set's entry in the response's `tiebreaks` array, so the two
            never disagree. The row that closes a set carries the decided games
            before the set counter catches up, and since 2026-09-24 the games
            on the row decide it, so the field does not depend on which row the
            counter moves on. Before that a set whose counter lagged by a row
            was never stamped and stayed empty on every later read, while
            `tiebreaks` stated the final.
          items: { type: integer }
          example: [2, 7]
        win_probability_p1:
          type: [number, "null"]
          description: >-
            The model read stamped on this row while the match was live.
            The tape carries NO model-regime stamp — there is no
            `model_version` or `generated_at` column here, nor in the bulk
            `tape` packages — so segregate a recorded tape corpus by this
            row's `timestamp` against the two regime boundaries documented on
            `Score.win_probability_meta`: 2026-08-18T08:29:28Z and
            2026-09-16T07:59:54Z.
        danger: { type: [number, "null"] }
        timestamp: { type: [string, "null"], format: date-time }
        accepted_at:
          type: [string, "null"]
          format: date-time
          description: >-
            On tape rows since 2026-09-24. The instant our arbiter accepted
            this state (UTC), stamped once at insert and never refreshed by a
            re-assertion. This is the clock to difference a timing study
            against: `timestamp` starts equal to it and is then refreshed while
            the owning source keeps re-asserting the unchanged state, so on
            most raw rows `timestamp` is a later re-assertion instant (measured
            on match 189679: 164 of its 171 observed rows carry a `timestamp`
            more than a second after `accepted_at`). Null on every
            reconstructed row, which never had a clock. IT ALSO HAS A START
            DATE ON THE ARCHIVED TAPE, and this description claimed the
            opposite ("it rides the whole observed corpus") until 2026-10-01.
            THAT DATE MOVED BACK SIX WEEKS ON 2026-10-01. A tape answered
            from the archive (`meta.from_archive: true`) now carries the clock
            on every observed row from 2026-08-11: 100.0% of every day from
            2026-08-11 to 2026-10-01, 92.5% of 2026-08-10 (the live column's
            own first instant is `2026-08-10T08:07:42Z`), and 0.0% of every day
            before that. Over the whole archived observed corpus, 1,721,102 of
            4,663,181 rows carry it (36.9%, against 307,631 before the
            backfill): 0.0% of every month to July 2026, 68.8% of August,
            100.0% of September and of October. The boundary was 2026-09-23,
            the day the archive column landed, until a backfill took each
            missing value from the live row that archived row had been copied
            from: 1,413,471 clocks and 1,393,458 counters, inside 1,538,176
            rows over 14,491 matches. Nothing is derived, rounded or taken from
            a neighbouring row, and a row whose live row was already trimmed at
            the 90-day retention stays null for good. Wire-verified on match
            2168 (26 April 2026), before the boundary: 131 observed rows,
            `timestamp` on all 131 and `accepted_at` on none. Match 189679's
            own archived copy carried the clock on 0 of its 171 observed rows
            before that run and on 171 of 171 after it, which is why the
            189679 measurement above holds either way: that match is served
            with `from_archive: false`. So read `meta.from_archive` before
            planning a timing study, and treat a null here as a boundary of the
            record rather than as a missing value.
        received_at:
          type: [string, "null"]
          format: date-time
          description: >-
            On tape rows since 2026-09-24. The instant this state reached our
            edge, before the arbiter ran, stamped once. `accepted_at` minus
            `received_at` is our own arbitration step; neither figure is a
            claim about how fast anything upstream is, and neither is the
            court's clock. `timestamp` is the only one of the three with no
            start date: this clock begins 2026-09-24 and `accepted_at` begins
            2026-08-11 on an archived tape (this description said the other
            two had no start date until 2026-10-01, which was wrong about
            `accepted_at` — see `HistoryTapeRow.accepted_at`). This is also the
            one clock the 2026-10-01 archive backfill could not move: the live
            column landed 2026-09-24, a day AFTER the archive column, so every
            live row carrying an arrival clock was archived with it and the
            recoverable count is zero. It is stamped
            only as a state arrives, so it can never be
            filled in afterwards: the earliest one we hold is
            `2026-09-24T02:00:26Z`, and on every observed row accepted before
            that instant it is null while `timestamp` is populated. Measured on match 189679 (12 September) after a Basic
            customer reported it on 2026-09-25: 171 observed rows,
            `accepted_at` on all 171, `received_at` on none — a match served
            from its live rows, so it says nothing about the archived tape.
            Null on every reconstructed row.
        sequence:
          type: [integer, "null"]
          description: >-
            On tape rows since 2026-09-26. This state's per-match ACCEPT
            COUNTER — the same number `GET /matches/{matchId}/withdrawals`
            publishes as `sequence` and `replaced_by_sequence`, and the same
            counter as `Score.sequence` on a live read. It is what makes the
            withdrawal ledger's pointer resolvable: told "sequence 104 was
            withdrawn, resume from 103", you can now find 103 on the tape, and
            because a withdrawn state never enters the record at all the
            withdrawal shows up here as a GAP in the run of counters. Before
            this the tape published no such number, so the pointer named a row
            nothing identified — reported by an Ultra customer who wrote that
            "the history rows lack sequence IDs, so these responses alone
            cannot reconstruct exactly what a live client received".
            NULL, NEVER FABRICATED, IN TWO CASES, and both are honest gaps
            rather than errors: a row whose archived copy could not be filled
            from its own live row, and the pre-2023 archive tape, which has no
            such counter because no live accept ever happened. The 2026-10-01
            backfill moved the first of those from 2026-09-26 back to
            2026-08-14, so the archived counter is on 68.2% of 2026-08-14,
            99.3% of 08-15, 95.9% or more of every day from 2026-08-16 and 100%
            from 2026-09-01; before that the counter died with the live row at
            the 90-day retention. Unlike the two
            clocks it is NOT null on a reconstructed row: a counter is a fact
            about our own accept order, so wherever one is present a live
            reader really did receive that state at that position.
        winner:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            Who won the point that produced this row — `1` | `2`, judged from
            the score step between this row and the previous served row (the
            previous raw row on the raw sequence, the previous clean row under
            `?sequence=clean`), by the same rule the completeness ledger
            counts a legal transition with — and from nothing else: never the
            serve, the server, the outcome tag or the pattern of play. Null on
            the first row and wherever the step is not one attributable
            point: a re-sent row (an identical state — null on raw, collapsed
            away on clean), a set opener (same games totals, the arrays
            extended by `[0,0]`), a backward correction, a multi-game jump. A
            step whose games total rises by exactly one attributes to the
            side whose count rose (the game point was theirs) whatever
            in-game points the step skipped — a missed poll, or a game the
            strict expander withheld whole; `meta.points.games_withheld` says
            when the latter happened. Present on every row of every sequence,
            observed and reconstructed, and on the pre-2023 ArchiveTape; equal
            to `point_winner` wherever that older key is present. Derived once
            per response, never stored. Added 2026-09-22.
        point_winner:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            The same verdict as `winner` under the older key, kept unchanged
            for existing readers. Who won the point this row records —
            PRESENT ONLY on
            `?sequence=clean` and `?points=complete` rows, and only where the
            transition from the previous row of the served sequence is a
            single attributable point; null on gaps, torn rows and the first
            row. Never on the plain raw sequence (raw is deliberately
            non-monotonic: consecutive raw rows are corrections, not points —
            a `points=complete` read is the exception, because there the
            served order IS point order). Derived at read time, never stored
            or guessed. Since 2026-09-22 `winner` carries the same verdict on
            every row of every sequence.
    HistoryTape:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/Match'
        tape:
          type: array
          description: Chronological score sequence — see HistoryTapeRow
          items:
            $ref: '#/components/schemas/HistoryTapeRow'
        tiebreaks:
          type:
          - array
          - 'null'
          description: >-
            Per-set tiebreak final scores, aligned to the sets of the final
            scoreline: {"p1", "p2"} for each 7-6 set, null per set otherwise;
            null when the match has no 7-6 set. Each entry comes from the
            tape's own terminal breaker state (max >= 7, margin >= 2 — always
            wins), a source's finished-match summary, or the point-by-point
            reconstruction — named per set in meta.tiebreaks_source. Nothing
            is inferred from a partial state: a breaker whose closing point no
            source states reads null rather than an under-report. Before
            2026-09-16 only the tape kind existed and the array was null on
            ~99% of 7-6 sets.
            TIMING. Only the `tape` kind is available the instant a match
            ends. `summary` and `reconstruction` entries are written by a
            finals pass that runs ONCE A DAY, so a match that finished
            earlier the same day commonly reads null for its
            7-6 sets and carries them from the next pass onward. Measured
            2026-09-17: of 7-6 sets in matches completed on the five previous
            days, 72-100% were populated; of those completed the same day,
            8%. Re-read a fresh match the following day before treating a
            null as final.
          items:
            type:
            - object
            - 'null'
            properties:
              p1:
                type: integer
              p2:
                type: integer
        profiles:
          type: array
          description: Model profiles, oldest first (Analysis `profile` shape)
          items:
            type: object
        meta:
          type: object
          properties:
            match_id:
              type: integer
            rows:
              type: integer
              description: Rows RETURNED — after any `sequence=clean` collapse.
            coverage:
              $ref: '#/components/schemas/Coverage'
            point_source:
              type:
              - string
              - 'null'
              enum:
              - observed
              - reconstructed
              - mixed
              - null
              description: Where the rows came from — `observed` (every row watched live), `reconstructed`
                (every row expanded after the fact), `mixed` (a reconstructed opening followed by what
                we watched), or null on an empty tape. Reported once here and never per row, so the row
                shape cannot carry data-source provenance.
            raw_rows:
              type: integer
              description: Rows BEFORE any collapse — equals `rows` when `sequence=raw`.
            unique_states:
              type: integer
              description: Distinct score states in the raw tape. `raw_rows` minus this is pure repetition.
            sequence:
              type: string
              enum:
              - raw
              - clean
              description: Echoes the requested `?sequence=`.
            from_archive:
              type: boolean
              description: The rows were served from the immutable archive rather than the live table.
                Informational — the content contract is identical.
            points:
              $ref: '#/components/schemas/PointsMeta'
            tiebreaks_source:
              type:
              - array
              - 'null'
              description: >-
                Aligned to the top-level `tiebreaks`: per set, where that
                set's breaker final came from — `tape` (the served tape
                reached a terminal breaker state), `summary` (a source's
                finished-match summary) or `reconstruction` (the
                point-by-point reconstruction) — or null where the entry is
                null. Null when `tiebreaks` is null. `summary` and
                `reconstruction` are written by the once-a-day finals pass
                (see `tiebreaks`), not at the moment a match ends.
              items:
                type:
                - string
                - 'null'
                enum:
                - tape
                - summary
                - reconstruction
                - null
            reconstructed_at:
              type:
              - string
              - 'null'
              format: date-time
              description: >-
                When the newest RECONSTRUCTED row in this response was written
                (UTC) — when the reconstruction you are holding landed. Null
                when no reconstructed row is served. Measured on the rows
                returned, after any sequence=clean collapse. Added 2026-09-20.
            observed_span:
              type:
              - object
              - 'null'
              description: >-
                The `timestamp` of the first and last OBSERVED rows in this
                response, in served order. Null when no observed row is
                served. Added 2026-09-20.
              properties:
                first:
                  type:
                  - string
                  - 'null'
                  format: date-time
                last:
                  type:
                  - string
                  - 'null'
                  format: date-time
            enrichment:
              type: object
              description: >-
                What serve/outcome tags actually landed on the rows of THIS
                response — the per-point stream's vocabulary. `none`/`none`
                on a wholly reconstructed tape. Added 2026-09-20.
              properties:
                serve:
                  type: string
                  enum:
                  - stated
                  - none
                outcome:
                  type: string
                  enum:
                  - full
                  - ace_double_fault
                  - none
            generated_at:
              type: string
              format: date-time
    PointsMeta:
      type: object
      description: >-
        Measured point-completeness of the sequence ACTUALLY RETURNED,
        computed at read time — never a stored blanket claim, and only ever a
        per-match measurement. Always present on `?points=complete` responses
        (with `available_complete`); on default reads it appears where
        enabled. Orthogonal to `coverage`: coverage says how the rows were
        OBTAINED, this says how COMPLETE the sequence is.
      properties:
        complete:
          type: boolean
          description: >-
            The contract bit: a statement that the served sequence holds AT
            LEAST EVERY POINT THE SCORE REQUIRES — not merely that consecutive
            rows are consistent with each other. True only when the sequence
            opens at 0-0, EVERY transition is a legal single-point step, it
            carries at least as many point transitions as the final scoreline
            implies the match contained, EVERY completed game holds at least
            as many point transitions as that game must have contained
            (`games_short` is 0 — a whole game the tape skips is a legal
            0-0 → 0-0 boundary the transition test alone cannot see, added
            2026-09-21), it reaches a finished legal final scoreline at love
            (or the match ended early — retirement/walkover), it is not
            known-truncated, and no game was withheld (`games_withheld`).
        completeness:
          type: [number, "null"]
          description: >-
            Legal single-point transitions over a LOWER-BOUND expected point
            count derived from the final scoreline. 1.0 for any complete
            tape, low for a sampled one. Descriptive only — the denominator
            is a floor, not the true point count — and null when the final
            scoreline is unreadable.
        rows:
          type: integer
          description: Rows measured — always equals `meta.rows`.
        transitions_legal:
          type: integer
          description: >-
            Transitions attributable to exactly one side winning one point.
        transitions_total:
          type: integer
          description: All row-to-row transitions, excluding re-sent rows (rows − 1 − `resent_rows`).
        resent_rows:
          type: integer
          description: >-
            Rows identical to the row before them — the same state re-sent
            by a source on its timer, which the raw tape carries by design.
            No point separates them, so they are excluded from the
            transition counts (`transitions_total` = `rows` − 1 −
            `resent_rows`) rather than counted as non-point steps. 0 on a
            `clean` or `recon` basis: the collapse removes them, and in a
            reconstruction one row IS one point so a repeat is a vendor tear
            and is never dropped. Added 2026-09-20.
        server_rows:
          type: integer
          description: Rows carrying a server.
        starts_at_love:
          type: boolean
          description: The first row is the 0-0 opening state.
        ends_at_final:
          type: boolean
          description: >-
            The last row is a complete, legal final scoreline AND shows no
            game in progress: points at love or null, not a tiebreak in
            progress. A row carrying a finished spine with a game still
            underway (e.g. [[6,6],[3,4]] at 15-0) reads false (since
            2026-09-21; before that the spine alone decided).
        basis:
          type: string
          enum: [raw, clean, recon]
          description: >-
            Which serve was measured: `raw` | `clean` (the default read, as
            returned) or `recon` (the whole reconstruction,
            `?points=complete`).
        available_complete:
          type: [boolean, "null"]
          description: >-
            `?points=complete` responses only. Whether a point-complete
            reconstruction exists for this match — never guessed. Nightly,
            refreshed on read when absent: the nightly ledger's verdict when
            it has one; when the ledger has no entry yet (a reconstruction
            that landed after the last nightly run) and this read served a
            reconstruction, it is the live verdict just measured on it
            (`complete`); null only when there is no ledger entry and nothing
            to measure. Added 2026-09-20.
        games_short:
          type: [integer, "null"]
          description: >-
            A completed game for which the tape holds fewer point transitions
            than that game must have contained; `> 0` forces `complete` to
            `false`; nothing is inferred or repaired. Counted by walking the
            sequence by game boundary and comparing what is held for each
            completed game with the FEWEST points that game can have
            contained given the last state it shows (from 0-0 at least 4;
            from 15-30 at least 5; from 40-40 at least 8; a tiebreak at least
            7) — a lower bound, never an estimate. A game the tape skips
            whole (0-0 → 0-0 with the games counter up by one) counts; so
            does a game that ended with no further rows after its last stored
            point. The game's boundary rows are still served exactly as
            stored. `null` = nothing measured (an empty sequence). Added
            2026-09-21.
        games_withheld:
          type: [integer, "null"]
          description: >-
            Present only when reconstructed rows are in the response. Games
            whose vendor point record was internally inconsistent (the
            recorded in-game scores do not form a legal single-point
            progression from 0-0 — a state repeating or moving backwards)
            have their in-game points withheld rather than published; the
            game's opening 0-0 row is still served, so the games spine stays
            intact. Nothing is repaired, reordered or inferred: a game is
            served exactly as recorded, or not at all. `> 0` means `complete`
            is `false`. `null` = not measured — the reconstruction predates
            this check, or was built from the multi-vendor union rather than
            a single vendor's point record. Added 2026-09-20.
    HistoryPackage:
      type: object
      description: >-
        Manifest of one pre-built bulk package (PRO, Historical Data API
        Pro+, or a one-off package pass). Tape coverage is not a contiguous
        run of months and is still being extended backwards, so treat the
        packages listing as the authoritative set of periods that exist. For
        `kind=tape` the JSONL file holds ONE LINE PER MATCH (a whole
        HistoryTape object per line, coverage meta included), not one line
        per point; the CSV is flattened to one row per point and carries no
        coverage columns. Under `schema_version` 2 (since 2026-09-22) each
        JSONL line is exactly what `GET /history/matches/{matchId}` returns
        for that match on its default basis, produced by the same code: the
        same tape rows with the same fields as the per-match tape (`origin`,
        `serve`, `outcome`, `winner` beside the score columns) and the same
        `meta` (`coverage`, `point_source`, `enrichment`, `reconstructed_at`,
        `observed_span`, `tiebreaks_source`, and `meta.points` whenever the
        endpoint serves it), so a model that initialises its serve states
        from `server` / `serve` / `winner` reads them from the bulk file just
        as it would from the endpoint. The CSV column order is stable and
        grows only at the end: `match_id`, `row`, `timestamp`, `sets_p1`,
        `sets_p2`, `games_p1`, `games_p2`, `points_p1`, `points_p2`,
        `server`, `is_tiebreak`, `win_probability_p1`, `danger` — the
        columns every month has ever carried — then, since schema version 2,
        `origin`, `serve`, `outcome`, `winner`, with the same values and
        vocabularies as the JSONL row (a null is an empty cell); read the
        header, not positions, for anything past `danger`. A month may also list the complete-basis ADDENDUM
        files (tennis_history_points_complete_<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=archive_tape` (the reconstructed 2013–2022
        point-by-point tape; ULTRA, History Pro/Business, or an active one-off
        package window) the JSONL record is byte-for-byte what
        `GET /history/archive/matches/{archiveId}/tape` returns — one whole
        ArchiveTape object per line, `meta` included — so a parser written
        against one match runs over a whole year unchanged; the CSV is the flat
        per-row view keyed on `archive_match_id` and deliberately carries NO
        `timestamp`, `win_probability_p1` or `danger` column, because a column
        empty in 100% of a file invites the belief that it is sometimes
        populated. Ten periods, `period` 2013 through 2022, each with a JSONL
        and a CSV file, all `ready`; no earlier year exists, because no tape
        earlier than 2013 exists.
        For `kind=elo` (the as-of Elo tape; ULTRA or History Pro/Business) the JSONL
        holds one rating record per line — the endpoint's field set plus
        `archive_player_id`, the stable person key a bulk join needs — and
        the CSV one row per record, one file per YEAR; the files are written
        in primary-key order, so a rebuild of the same data is byte-identical
        and the published `sha256` is a real checksum.
      properties:
        period:
          type: string
          description: >-
            Calendar month, `YYYY-MM` — or the bare year `YYYY` on the yearly
            `rally`/`archive`/`elo`/`archive_tape` kinds.
        status:
          type: string
          enum: [ready]
          description: Only built months are listed or served.
        match_count: { type: [integer, "null"] }
        row_count: { type: [integer, "null"] }
        files:
          type: array
          description: One entry per downloadable format.
          items:
            type: object
            properties:
              format: { type: string, enum: [jsonl, csv] }
              filename: { type: string }
              bytes: { type: integer }
              sha256: { type: string }
              compression:
                type: string
                enum: [gzip]
                description: >-
                  Present only on compressed files (the yearly kinds and the
                  points_complete addendum ship gzipped). `bytes` and `sha256`
                  cover the COMPRESSED bytes — exactly what you download.
        built_at: { type: [string, "null"], format: date-time }
        schema_version:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            Which shape this month's files carry (added 2026-09-22), so you
            can tell without opening them. `2` = a package row is the API
            tape row (`origin`, `serve`, `outcome`, `winner`, and the full
            `meta`), and the CSV carries the trailing columns. `1` = the
            shape every month built before 22 September 2026 carries: tape
            rows hold the score columns only (no `origin`, `serve`, `outcome`
            or `winner`; no `meta.enrichment`, `reconstructed_at` or
            `observed_span`), and the CSV ends at `danger`. Months built
            before 22 September 2026 keep this shape UNTIL THEY ARE REBUILT;
            the rebuild runs newest month first, then backwards, and a
            month's `schema_version` flips to `2` (and its `built_at` and
            `sha256` values move) when its turn comes. Check the manifest
            rather than assuming a month is one or the other: a consumer that
            needs the enriched fields should require `schema_version >= 2`
            and, for a month still at `1`, read the per-match endpoint for
            the matches it needs. `null` = not versioned: the non-tape kinds
            (`rankings`, `elo`, …).
        kind:
          type: string
          enum: [tape, rankings, rally, archive, elo, archive_tape]
          description: >-
            Present only on non-tape packages, so the shape a tape client
            already parses is unchanged. On a rankings package `match_count` is
            the number of players covered and `row_count` the number of ranking
            records; on a rally package the counts are charted matches and
            points; on an archive package the counts are archive results; on
            an `elo` package `row_count` is the number of rating records; on an
            `archive_tape` package `match_count` is the reconstructed tapes in
            that year and `row_count` their score rows (97,901 and 14,340,663
            across the ten years).
    Coverage:
      type: string
      enum: [from_start, partial, reconstructed, reconstructed_partial, none]
      description: >-
        How a tape came to exist, and specifically whether we WATCHED it.
        `from_start` — we watched this match live from 0-0; every row was
        committed by our own pipeline while the point was being played, so
        every row carries a real timestamp. It is a statement about how the
        rows were obtained, NOT a synonym for "complete".
        `partial` — we watched it, but recording began after play had started
        and no reconstruction is available to repair the opening.
        `reconstructed` — the tape opens with rows expanded after the fact from
        a finished-match point-by-point record: either the whole tape (we never
        watched the match) or its unwatched opening followed by what we did
        watch. True about the score, silent about the clock.
        `reconstructed_partial` — as `reconstructed`, AND the reconstruction is
        known not to cover the whole match. That happens two ways: it OPENS
        AFTER 0-0 (the upstream record begins mid-match), or it STOPS SHORT of
        the official final score (the record truncated, usually by the deciding
        game). Every row is still a point somebody recorded — nothing is
        synthesised to close either gap — but the match is NOT complete and
        must not be backtested as if it were.
        `none` — no rows; the match was on the calendar and was neither watched
        nor reconstructable.
        This vocabulary describes the 2023+ tape. The 2013–2022 archive tape
        (`ArchiveTape`) reuses it restricted to `reconstructed` and
        `reconstructed_partial`, and derives the second DIFFERENTLY: there a
        per-GAME tape carries that label however complete it is — see
        `ArchiveTape.meta.coverage` before reading it the same way.
    CoverageRollup:
      type: object
      description: >-
        The measured completeness rollup — what the archive HOLDS, per tour ×
        draw bucket, as of the artifact's own build clock.
      properties:
        as_of:
          type: string
          format: date-time
          description: >-
            Equal to `built_at`, verbatim — the artifact's own clock, and the
            date to quote with every number in this response.
        built_at:
          type: string
          format: date-time
          description: When the rollup was built (UTC).
        ledger_max_computed_at:
          type: [string, "null"]
          format: date-time
          description: >-
            The newest underlying per-match measurement in the completeness
            ledger.
        method:
          type: string
          description: >-
            The full measurement rule for point_complete, in one paragraph —
            every number carries its own definition.
        buckets:
          type: object
          description: >-
            One CoverageBucket per tour × draw bucket (`atp_singles` …
            `juniors_doubles`, plus `other`). A bucket with zero completed
            matches is OMITTED rather than emitted as zeros — read a missing
            key as "nothing to count", not an error.
          additionalProperties: { $ref: "#/components/schemas/CoverageBucket" }
        totals:
          $ref: "#/components/schemas/CoverageBucket"
    CoverageBucket:
      type: object
      description: The five verifiable numbers for one bucket.
      properties:
        completed:
          type: integer
          description: Completed matches in the bucket.
        any_tape:
          type: integer
          description: Matches with at least one tape row on any basis.
        point_complete:
          type: integer
          description: >-
            Measured point-complete on the BEST basis — what
            `?points=complete` can serve.
        complete_on_default_read:
          type: integer
          description: >-
            Point-complete on the default read alone. The difference against
            `point_complete` is the set of matches where `?points=complete` is
            load-bearing.
        share:
          type: [number, "null"]
          description: point_complete / completed. Null on an empty bucket.
    HistoryMatch:
      allOf:
        - { $ref: "#/components/schemas/Match" }
        - type: object
          properties:
            tape:
              type: object
              description: What point-by-point data we hold for this match.
              properties:
                coverage: { $ref: "#/components/schemas/Coverage" }
                rows:
                  type: integer
                  description: >-
                    Rows we OBSERVED (watched live). This is not the length of
                    the tape you will be served: a reconstructed or mixed tape
                    also includes reconstructed rows, and for a
                    partially-watched match only a prefix of the reconstruction
                    is spliced in front. Use `meta.rows` on the per-match tape
                    for the served length.
                reconstructed_rows:
                  type: integer
                  description: Reconstructed rows available for this match.
                model_rows:
                  type: integer
                  description: >-
                    How many of the OBSERVED rows carry a non-null
                    `win_probability_p1`. The model stamp is best-effort and
                    no coverage value — `from_start` included — implies it;
                    read this number to select tapes the model actually
                    scored.
                points_complete:
                  type: [boolean, "null"]
                  description: >-
                    Measured point-completeness, best basis: true when the
                    served tape OR an on-disk reconstruction of the match
                    measured point-complete (fetch the latter with
                    `?points=complete` on the per-match tape); null when the
                    match has not been measured yet — never a guess. Since
                    2026-09-20 the served-tape leg judges the same raw
                    sequence (provable re-sends dropped) that the per-match
                    read serves and measures in `meta.points`, so the two
                    agree by construction; a row scored before the switch may
                    still disagree until the nightly re-score reaches it
                    (see `points_basis`). Read from a per-match ledger
                    reconverged nightly. Present where enabled.
                points_complete_default:
                  type: [boolean, "null"]
                  description: >-
                    WHICH measurement produced `points_complete` — this one
                    is the served tape, measured on `points_basis`. Since
                    2026-09-20 that basis is the same raw sequence the
                    per-match read serves (re-sends dropped), so this field
                    and that read's `meta.points.complete` agree by
                    construction instead of disagreeing on a collapse the
                    read never served. Null when that basis was not
                    measured. Added 2026-09-20 after a consumer filtered on
                    `points_complete=true`, fetched a match and read
                    `meta.points.complete: false`: both answers were honest
                    about their own sequence, and nothing in the payload
                    said which sequence each had judged. Present where
                    enabled.
                points_complete_recon:
                  type: [boolean, "null"]
                  description: >-
                    The other half of `points_complete`: the on-disk
                    reconstruction, which you fetch with `?points=complete`
                    on the per-match tape. Null when no reconstruction
                    existed when the ledger last ran. A complete
                    reconstruction is a different object from a complete
                    observed tape — every row carries a null `timestamp` and
                    null model fields, because neither ever existed for it.
                    Present where enabled.
                points_basis:
                  type: [string, "null"]
                  enum: [clean, raw, null]
                  description: >-
                    Which sequence `points_complete_default` judged — `raw`,
                    the same sequence the per-match read serves (provable
                    re-sends dropped, exactly as that read's `meta.points`
                    judges it), for an observed tape and a served
                    reconstruction alike. `clean` — the collapsed one row
                    per distinct state, still obtainable with
                    `?sequence=clean` as a request option — appears only on
                    a row scored before 2026-09-20 that the nightly
                    re-score has not yet reached. Null when not measured.
                    Present where enabled.
                completeness:
                  type: [number, "null"]
                  description: >-
                    The better of the two measured completeness fractions
                    (0..1, lower-bound denominator — see the per-match tape's
                    `meta.points`). Null when not measured. Present where
                    enabled.
                starts_at_love:
                  type: [boolean, "null"]
                  description: >-
                    Whether a measured basis OPENS at the 0-0 state — the SAME
                    best-basis rule as points_complete: true when either basis
                    starts at love, so if any on-disk sequence opens at 0-0
                    you can obtain one that does. Null when the match has not
                    been measured. Present where enabled.
                computed_at:
                  type: [string, "null"]
                  format: date-time
                  description: >-
                    When the ledger last measured this match, UTC with a
                    trailing `Z` — the same projection every other clock in
                    this payload uses, so it can be diffed against
                    `meta.generated_at` or a row's `timestamp` without
                    normalising it by hand first. Every field in this block
                    is a nightly-reconverged cache; this is the as-of to
                    quote with any of them. Null when the match has not been
                    measured. Present where enabled.
    Usage:
      type: object
      properties:
        principal: { type: string, description: "Opaque ref to your own key" }
        tier: { type: string, enum: [free, basic, pro, ultra] }
        base_tier:
          type: string
          description: >-
            Subscription tier; equals `tier` unless a temporary grant is active
        tier_expires_at:
          type: [string, "null"]
          format: date-time
          description: When a temporary tier grant reverts, else null
        channel: { type: string }
        limits:
          type: object
          properties:
            per_minute: { type: [integer, "null"] }
            per_day: { type: [integer, "null"] }
        today:
          type: object
          properties:
            calls: { type: integer }
            errors: { type: integer }
            remaining_day:
              type: [integer, "null"]
              description: >-
                Requests still SERVABLE today: the day allowance less SERVED calls (`calls - errors`). Refused requests never spend the allowance, so this does not fall when a `429`, `403` or `404` is returned. Null when the tier carries no day cap.
        history:
          type: array
          description: Last 30 days, oldest first
          items:
            type: object
            properties:
              day: { type: string, format: date }
              calls: { type: integer }
              errors: { type: integer }
        as_of: { type: string, format: date-time }
    MatchStatisticsSide:
      type: object
      description: >-
        One player's in-play statistics, in TWO families that are deliberately
        not merged. The fields at this level are DERIVED from the
        point-by-point record. `measured` holds counts taken upstream,
        including the ones no point record can yield: aces, double faults, the
        serve split, winners and unforced errors. Both families name some of
        the same quantities, computed two entirely different ways — that is a
        cross-check, not a duplication to be collapsed.
      properties:
        measured:
          $ref: "#/components/schemas/MatchStatisticsMeasured"
        service_games_played: { type: integer }
        service_games_won: { type: integer }
        hold_pct:
          type: [integer, "null"]
          description: >-
            null when no service game was played — never 0, so a present 0 is a
            real measured zero
        return_games_played: { type: integer }
        return_games_won: { type: integer }
        break_pct: { type: [integer, "null"] }
        break_points_faced: { type: integer }
        break_points_saved: { type: integer }
        break_points_saved_pct: { type: [integer, "null"] }
        break_points_played: { type: integer }
        break_points_converted: { type: integer }
        break_points_converted_pct: { type: [integer, "null"] }
        service_points_played: { type: integer }
        service_points_won: { type: integer }
        service_points_won_pct: { type: [integer, "null"] }
        return_points_played: { type: integer }
        return_points_won: { type: integer }
        return_points_won_pct: { type: [integer, "null"] }
        points_played: { type: integer }
        points_won: { type: integer }
    MatchStatisticsMeasured:
      type: object
      description: >-
        Measured counting statistics for one player. These are COUNTED
        upstream, not derived from the point record — which is why they can
        include aces and double faults, and the derived fields above cannot.
        They are MATCH TOTALS only — one whole-match rollup per player; there
        are no per-set measured statistics.

        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, atp_doubles, wta_doubles]
        tour: { type: [string, "null"] }
        rank:
          type: [integer, "null"]
          description: >-
            Null for UTR. Null for `elo` in per-player mode too — an Elo has
            no global rank at a past instant until you say which field and
            which activity window you mean, and the per-player read is given
            neither. In `elo` listing mode it is the position in the
            qualified field of THAT call.
        points:
          type: [integer, "null"]
          description: >-
            Null for UTR and for `elo` — both are ratings, and neither has
            points.
        surface:
          type: string
          enum: [overall, hard, clay, grass]
          description: >-
            `elo` only, and absent on every other system. Which of the four
            independent ladders this rating is. A ladder the player has never
            played is omitted from the response rather than substituted with
            another.
        matches:
          type: [integer, "null"]
          description: >-
            `elo` only, and absent on every other system. Cumulative matches
            on THAT ladder at that date — not the player's career total.
            Every ladder starts at 1500, so this is what tells you whether a
            rating is an assessment or a cold start, and it is the number
            `min_matches` filters on.
        previous_rank:
          type: [integer, "null"]
          description: >-
            The rank at the immediately preceding snapshot week (ATP/WTA
            only; null when no prior week is held, and always null for
            ITF/UTR).
        rank_movement:
          type: [integer, "null"]
          description: >-
            The circuit's own signed weekly movement (ITF systems only; null
            elsewhere).
        rating:
          type: [number, "null"]
          description: >-
            UTR and `elo` only; null elsewhere. For `elo` this is the Elo
            itself, on our own scale, which is not comparable with Elo
            published anywhere else.
        effective_date:
          type: [string, "null"]
          format: date
          description: >-
            The publication week this record took effect. For records ingested
            live rather than from the official weekly publication this is
            bucketed to the observed week, so it can sit up to six days later
            than the moment the value actually took effect; where both exist
            for one week the official publication is served.
        observed_at: { type: [string, "null"], format: date-time }
    RankingListMeta:
      allOf:
        - $ref: "#/components/schemas/ListMeta"
        - type: object
          properties:
            coverage:
              type: object
              description: >-
                What resolved against what was asked. Read it before trusting
                an empty result — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29); nothing earlier can be reconstructed, so a request before `oldest_available` correctly returns nothing for those systems.
              properties:
                as_of: { type: [string, "null"], format: date }
                effective_date:
                  type: [string, "null"]
                  format: date
                  description: >-
                    Listing mode. For the official systems, the published
                    week the table is from. For `elo`, the as-of instant the
                    leaderboard was resolved at (each row carries its own
                    `effective_date`, since a sparse tape moves per player).
                players_requested:
                  type: integer
                  description: Per-player mode only.
                players_resolved:
                  type: integer
                  description: Per-player mode only.
                systems_requested: { type: array, items: { type: string } }
                systems_resolved: { type: array, items: { type: string } }
                oldest_available:
                  type: object
                  additionalProperties: { type: [string, "null"], format: date }
                  description: >-
                    Earliest effective date held, per requested system.
                newest_available:
                  type: object
                  additionalProperties: { type: [string, "null"], format: date }
                  description: >-
                    Present only when `elo` was requested. The NEWEST
                    effective date the Elo tape holds. The corpus behind it
                    is fixed and no longer receives new results, so this
                    date does not advance and will keep receding from
                    today — that is a property of a historical tape, not a
                    fault. Read it before treating an Elo leaderboard as a
                    current one.
                tour:
                  type: [string, "null"]
                  description: >-
                    Present only when `elo` was requested — which walk
                    answered.
                surface:
                  description: >-
                    Present only when `elo` was requested. The ladder
                    (listing) or the list of ladders (per-player) the
                    response covers.
                players_rated:
                  type: integer
                  description: >-
                    Present only when `elo` was requested. People with at
                    least one rating in the tape.
                players_linked:
                  type: integer
                  description: >-
                    Present only when `elo` was requested. How many of those
                    have a row in our player roster, and therefore can be
                    reached with `player`. The rest are reachable with
                    `archive_player` and appear on the leaderboard with a
                    null `player_id` and their name. The gap between these
                    two numbers is large and is reported rather than buried.
                qualified:
                  type: object
                  description: >-
                    Present only on an `elo` listing. The two filters that
                    DEFINE the field this table ranks. A top-N is not
                    quotable without them — change either and it is a
                    different top-N, and neither is more correct than the
                    other.
                  properties:
                    activity_weeks: { type: integer }
                    min_matches: { type: integer }
                model:
                  type: object
                  description: >-
                    Present only when `elo` was requested. What the numbers
                    ARE.
                  properties:
                    name: { type: string }
                    start_rating: { type: number }
                    k_base: { type: number }
                    publication_lag_days:
                      type: integer
                      description: >-
                        A result becomes effective this many days after its
                        tournament WEEK begins. The corpus dates a match by
                        its tournament start, so without the lag a Slam
                        final would be visible under the Monday the Slam
                        began. The lag clears the longest event in tennis,
                        so the failure direction is staleness and never
                        look-ahead.
                    built_at: { type: [string, "null"], format: date-time }
                    note: { type: string }
    Webhook:
      type: object
      properties:
        id: { type: integer }
        url: { type: string }
        events:
          type: array
          items: { type: string, enum: [score, break_point] }
        enabled:
          type: boolean
          description: >-
            Set to false automatically after 25 consecutive delivery failures —
            delete and re-register to resume.
        created_at: { type: [string, "null"], format: date-time }
        last_delivery_at: { type: [string, "null"], format: date-time }
        consecutive_failures: { type: integer }
        last_error: { type: [string, "null"] }
        secret:
          type: string
          description: >-
            Present ONLY on the 201 registration response — shown exactly once
        secret_note: { type: string }
    BreakPoint:
      type: object
      description: >-
        WebSocket `break_point` frame (ULTRA). Pushed the instant a break point
        arises, but only when the subscription named `break_point` in its
        `signals`. Fields sit inline (no nested score object); `prob_swing`
        mirrors the REST score's `danger`. `server` is the player serving,
        `returner` the one holding the break point(s).
      properties:
        type: { type: string, const: break_point }
        match_id: { type: integer }
        server: { type: [integer, "null"], enum: [1, 2, null] }
        returner: { type: [integer, "null"], enum: [1, 2, null] }
        break_points:
          type: [integer, "null"]
          description: How many break points are live at once (1-3).
        set: { type: [integer, "null"] }
        game: { type: [integer, "null"] }
        point: { type: [string, "null"] }
        win_probability_p1: { type: [number, "null"] }
        prob_swing: { type: [number, "null"] }
        server_side_favoured: { type: [boolean, "null"] }
        ts: { type: [string, "null"], format: date-time }
    BreakPointResult:
      type: object
      description: >-
        WebSocket `break_point_result` frame (ULTRA): a break point just
        resolved. `outcome` is `held` (server saved it) or `broken` (returner
        converted); `win_probability_p1_after` is p1's win probability once the
        game closed.
      properties:
        type: { type: string, const: break_point_result }
        match_id: { type: integer }
        server: { type: [integer, "null"], enum: [1, 2, null] }
        outcome: { type: string, enum: [held, broken] }
        win_probability_p1_after: { type: [number, "null"] }
        ts: { type: [string, "null"], format: date-time }
    LivePoint:
      type: object
      description: >-
        One PLAYED point of a live match — the expanded score state AFTER the
        point. `seq` is per-match, monotonic and never skips a value: the
        ordering, dedup and resume key across the WS frames, the webhook
        deliveries and the REST catch-up read. `ts` is CAPTURE time (when our
        pipeline committed the state), never a per-point clock — no feed
        asserts one and we fabricate none.
      properties:
        seq:
          type: integer
          description: >-
            Per-match monotonic position 1..N — dedup and resume on this.
        set: { type: [integer, "null"] }
        game:
          type: [integer, "null"]
          description: Game within the current set — 13 for a 6-6 tiebreak.
        number:
          type: [integer, "null"]
          description: >-
            Points already recorded in this game at this state — 0 for a
            game's opening state, and **null when we joined the game already
            in progress**: how many points it holds is not derivable from the
            score (the deuce zone maps many ordinals onto one score) and is
            never guessed. `(set, game, number)` is NOT a unique key — a game
            re-expanded by a second source legitimately re-asserts ordinals it
            already holds, so the same tuple can name more than one row.
            `seq` is the only unique, stable per-row key.
        tiebreak: { type: boolean }
        server:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            Server of the point played FROM this state; null when the feed
            omits it.
        winner:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            Who won the point that produced this state — null when not
            attributable to a single point, never guessed.
        score:
          type: object
          description: >-
            In-game score AFTER the point ('0'/'15'/'30'/'40'/'AD'; the
            running tiebreak count as integer strings when `tiebreak` is
            true).
          properties:
            p1: { type: [string, "null"] }
            p2: { type: [string, "null"] }
        sets:
          type: array
          items: { type: [integer, "null"] }
        games:
          type: array
          description: >-
            `[games_p1, games_p2]`; each a per-set list, frozen at the
            pre-breaker score during a tiebreak.
          items:
            type: array
            items: { type: integer }
        ts:
          type: [string, "null"]
          format: date-time
          description: >-
            Capture time (UTC) — when our pipeline committed this state. Null
            on every frame of a `reconstruction`-basis page — the recorded
            sequence carries no per-point clock and none is fabricated. On
            the match-closing row of a completed match it is the instant the
            final score was observed.
        serve:
          type: [integer, "null"]
          enum: [1, 2, null]
          description: >-
            Added 2026-09-12. The serve the point was played on (1 first, 2
            second) as an outside source states it, joined onto the row by
            exact state. Null = not stated for this point; never inferred. A
            source point whose serve number and outcome contradict each other
            (a double fault stated on a first serve) is served untagged —
            `serve` and `outcome` both null — rather than tagged wrongly;
            nothing is corrected to a second serve (since 2026-09-21).
            Lands a few seconds after the point's own frame (see the
            `point_update` frame). Stated on the ATP main tour, ATP Challenger,
            WTA 1000/500/250/125, UTR and the top Davis Cup tiers; not stated
            on the ITF World Tennis Tour, nor in any doubles draw.
            EVERY COUNT BELOW IS WHAT THIS ENDPOINT PUBLISHES, not what we
            store, and on completed matches the two differ (corrected
            2026-09-23; the figures published before that date were counted in
            our own tables and overstated what a reader could fetch). A
            completed match whose stored per-point stream does not pass our
            quality bar is served as a measured-complete RECONSTRUCTION
            instead, and a reconstruction carries no clock and no tags at all
            — so per-match tag coverage on completed matches is lower, often
            much lower, than the share of matches a source tagged. `basis`
            on this response names which one you were given.
            Team ties, re-measured 2026-09-23 over completed matches with a
            per-point stream since 2026-09-12: Davis Cup World Group publishes
            `serve` on 2 of 22 and World Group I on 1 of 42, while World Group
            II publishes it on 0 of 38 — against 22 of 22 and 41 of 42
            respectively in storage, which is the gap this paragraph is about.
            Qualifying draws are covered like their own main draw, not
            excluded, and land in the same place their main draw does: WTA
            qualifying 18 of 48 against 50 of 88 in the WTA main draw, ATP
            Challenger qualifying (`tier: challenger_*`) 137 of 197 against
            221 of 285, and WTA 125 qualifying (`tier: wta_125`, also carried
            under `tour: challenger`) 47 of 63 against 117 of 147. Read
            `enrichment` per match — it is the only per-match answer, none
            of this is a promise about a match not yet played. Since
            2026-09-22, on the tours whose own point-by-point console we read
            (ATP 250/500/1000, ATP Challenger, WTA 1000/500/250/125), a
            COMPLETED match is re-joined after the match against the console's
            complete sequence by the same exact-state rule, so a completed
            match's serve/outcome coverage exceeds what was captured live —
            the tags arrive as `point_update` frames and `tagged_at`
            revisions like any other.
        outcome:
          type: [string, "null"]
          enum: [ace, double_fault, winner, forced_error, unforced_error, null]
          description: >-
            Added 2026-09-12. How the point ended, as an outside source states
            it. ATP 250 / 500 / 1000: serve stated, outcome full (ace, double
            fault, winner, forced error, unforced error) from the tour's own
            per-point console. Grand Slams and Davis Cup are not on that
            console, so `outcome` reads null there — but `serve` comes from a
            different source and IS stated on them, so those matches are not
            blanket-null; read `enrichment` per match. First
            measured on tour events from the week of 2026-09-22 — before that,
            no tour event had been played since the source went live on
            2026-09-12. ATP Challenger — `tour: challenger` with a
            `challenger_*` tier — states all five. `tour: challenger` also
            carries the WTA 125 events (`tier: wta_125`), and those state ace
            and double fault only, so read `tier` rather than `tour` to tell
            the two apart. The ITF World Tennis Tour: ace and double fault.
            WTA 1000/500/250/125: ace and double fault where the tour's
            console reports the match — read the page's `enrichment` per
            match. Grand Slams and UTR: none. ITF World Tennis Tour
            DOUBLES draws state ace and double fault on a growing minority of
            matches — the tags first reached a doubles row on 2026-09-23 and
            the endpoint published them on 104 of 596 completed doubles matches
            (17%) measured 2026-09-29, so read `enrichment` per match here and
            do not plan a corpus on the draw. Every other doubles draw
            (ATP, WTA and Challenger): none, measured 0 of 371 in the same
            window. Qualifying
            draws mostly follow their own tour, and the one real gap is on the
            WTA main tour, not on Challenger. EVERY COUNT BELOW IS WHAT THIS
            ENDPOINT PUBLISHES rather than what we store (corrected
            2026-09-23 — see the note on `serve` above: a completed match
            served on the `reconstruction` basis carries no tags, so the
            published share is below the share we hold). Re-measured
            2026-09-23 over completed matches carrying a per-point stream
            since 2026-09-12: ATP qualifying publishes outcome on 16 of 16 and
            ATP Challenger qualifying on 134 of 197, both the full five; ITF
            qualifying publishes aces and double faults on 181 of 215 men's
            and 142 of 176 women's, and WTA 125 qualifying on 30 of 63 — while
            WTA main-tour qualifying publishes it on 5 of 48, against 47 of 88
            in the same events' main draws. Read `enrichment` per match rather
            than inferring a draw's coverage from its tour. Null = not
            stated. A source point whose serve number and outcome contradict
            each other (a double fault stated on a first serve) is served
            untagged — `serve` and `outcome` both null — rather than tagged
            wrongly (since 2026-09-21). Since 2026-09-22, on the tours whose
            own point-by-point console we read (ATP 250/500/1000, ATP
            Challenger, WTA 1000/500/250/125), a COMPLETED match is re-joined
            after the match against the console's complete sequence by the
            same exact-state rule, so a completed match's coverage exceeds
            what was captured live — collect the late tags with
            `?changed_since=` or the `point_update` frame.
        tagged_at:
          type: [string, "null"]
          format: date-time
          description: >-
            Added 2026-09-20. When `serve`/`outcome` landed on this row
            (UTC); null while no tag has — on every `reconstruction`-basis
            frame, on the match-closing row, and on any row no source
            tagged. Tags land a few seconds after the row itself, so a row's
            `tagged_at` is later than its `ts`; `changed_since` selects on
            either.
        tiebreak_final:
          type: [array, "null"]
          items:
            type: integer
          minItems: 2
          maxItems: 2
          description: >-
            Added 2026-09-23. The breaker's closing score, in our player
            order, e.g. `[7, 5]`. Present ONLY on the row that closes a
            tiebreak set — the set roll-up (`tiebreak` false, the set banked
            7-6, `score` 0-0), which is the row carrying the breaker's
            winning point, every row being the state after a point. Absent
            on every other row, including the breaker rows themselves.
            Exact when the previous row is the decided score or one point
            from it (6-5 for the set's winner gives `[7, 5]`); otherwise
            taken from the match's recorded tiebreak finals, the same finals
            `GET /history/matches/{matchId}` publishes as `tiebreaks`; null
            when neither can state it. Never guessed. A page that *starts*
            on a roll-up row (an `after_seq` landing exactly there) reads the
            one row before your page, so the value does not depend on where
            the page was cut (since 2026-09-24; before that such a page used
            the recorded finals alone, and so read null on a set that closed
            while the match was still live). The deciding set of a
            match-tiebreak format is judged under the 10-point rule.
    PointUpdate:
      type: object
      description: >-
        Added 2026-09-12. Pushed on the point opt-in (`signals:["points"]`,
        channels `point:match:{id}` / `point:slate`) when a point's `serve` /
        `outcome` land after its `point` frame went out. Apply to the row with
        that `seq`; nothing else on the point changes.
      properties:
        type: { type: string, enum: [point_update] }
        match_id: { type: integer }
        seq: { type: integer }
        serve: { type: [integer, "null"], enum: [1, 2, null] }
        outcome: { type: [string, "null"], enum: [ace, double_fault, winner, forced_error, unforced_error, null] }
    MatchPoints:
      type: object
      description: >-
        One page of a match's per-point stream, seq order. `basis` says which
        base served it: the persisted live stream rows, or — for a completed
        match where a measured-complete recorded sequence exists — that
        complete sequence projected into point frames.
      properties:
        match_id: { type: integer }
        pbp_coverage:
          type: string
          enum: [point, game]
          description: >-
            `point` = a per-point stream has DELIVERED for this match (a played
            point past the seq-1 opener); `game` = no played point has arrived —
            only the snapshot score path covers it, or the stream holds only its
            opener so far (an answer, not an error; flips to `point` on the
            first played point — gate on `last_seq > 1`).
        quality:
          type: string
          enum: [clean, revised]
          description: >-
            `revised` = the upstream feed rewrote an already-served prefix at
            least once during this match; served rows are never edited.
        enrichment:
          type: object
          description: >-
            Added 2026-09-12. What an outside source has stated for THIS match
            so far — `serve`: stated | none; `outcome`: full |
            ace_double_fault | none. Read it before building on the fields;
            it is never a promise about the rest of the match.
          properties:
            serve: { type: string, enum: [stated, none] }
            outcome: { type: string, enum: [full, ace_double_fault, none] }
        covers_from_start:
          type: [boolean, "null"]
          description: >-
            Whether the persisted stream OPENS at the match's 0-0 opener —
            seq 1 exists and is the love-love state — i.e. whether replaying
            from `after_seq=0` yields the whole match or joins it mid-play.
            Null when the match has no rows at all (nothing to judge — null
            means not measured, never "no").
        points:
          type: array
          items: { $ref: "#/components/schemas/LivePoint" }
        last_seq:
          type: integer
          description: The resume cursor — pass as `after_seq` to continue.
        has_more: { type: boolean }
        basis:
          type: string
          enum: [live, reconstruction]
          description: >-
            Which base served this page. `live` = the persisted live stream
            rows, served whenever the stream is complete, or tagged and legal
            end to end (a projection carries no clock and no tag, so the
            stream is strictly more information); `reconstruction` = the
            complete recorded point sequence of a finished match, projected
            into point frames at read time, served only when the stream falls
            short (see `basis_reason`) — includes the match-closing point,
            `seq` contiguous 1..N, `ts` null on every frame. The two bases
            are never interleaved.
        basis_reason:
          type: string
          enum: [stream_absent, stream_incomplete, stream_illegal]
          description: >-
            Added 2026-09-21. Present on the `reconstruction` basis only — why
            the stored live stream was not served. `stream_absent` = no
            stream rows; `stream_incomplete` = the stream is legal but does
            not measure complete (joined mid-match or stopped short) and
            carries no tags; `stream_illegal` = at least one transition is
            not attributable to one point (a gap or a torn row). A stream
            that is complete, or tagged and legal end to end, is always
            served (basis `live`) and this key is absent.
        ends_at_final:
          type: boolean
          description: >-
            Added 2026-09-20. Whether the sequence served ends on the
            match-closing point — the state after the match-winning point:
            `number` 0, score 0-0, `server` null, `winner` the match winner.
            On a completed match served on the `live` basis that row is
            appended at read time from the stored stream's last row and the
            observed final score, and only when the two are one point apart
            (when the match ends in a tiebreak, the set roll-up after the
            decisive tiebreak row: `tiebreak` false, the set banked 7-6, the
            same `winner`); false when the match is completed but the stream
            stops short of it (a retirement or walkover, a truncated capture,
            or a closer that cannot be stated as one point, such as a
            10-point match tiebreak), and always false on a live match. On
            the `reconstruction` basis it is judged from the last projected
            frame.
    PointFrame:
      type: object
      description: >-
        WebSocket `point` frame (ULTRA, opt-in via
        `signals: ["points"]`; also the webhook `point` event body): one
        PLAYED point of a subscribed match. `seq` is arrival order, not match
        order — dedup/resume on it, and sort by `(set, game, number)` to replay
        in playing order (that tuple may repeat or carry a null `number`; it
        orders points, it does not identify them). Best-effort, NO replay — catch up via
        `GET /matches/{matchId}/points?after_seq=`.
      properties:
        type: { type: string, const: point }
        published_at:
          type: string
          format: date-time
          description: >-
            Added 2026-09-12, on EVERY data frame of the native WebSocket and the
            push feed (score, point, point_update, status, the signal family):
            the UTC instant (ms) the frame left our process for the socket or
            the fan-out sidecar — the third clock next to the state's
            `timestamp` (arbiter commit) and a point's `ts` (capture).
        match_id: { type: integer }
        point: { $ref: "#/components/schemas/LivePoint" }
        pbp_coverage: { type: string, enum: [point, game] }
        quality: { type: string, enum: [clean, revised] }
    Tournament:
      type: object
      description: >-
        One tournament of the catalogue — the stable id space
        `Match.tournament_id` joins, one row per tournament × event type,
        stable across seasons.
      properties:
        id:
          type: string
          description: The stable id `Match.tournament_id` joins.
        name: { type: [string, "null"] }
        tour:
          type: [string, "null"]
          enum: [atp, wta, challenger, itf, juniors, null]
        surface:
          type: [string, "null"]
          enum: [hard, clay, grass, null]
          description: >-
            Court surface, null where the catalogue holds none — 61 of 10,287
            tournaments on 2026-09-20. 35 of those are team competitions (Davis
            Cup, Billie Jean King Cup, Laver Cup), which have no tournament-level
            surface to hold: each tie is played on the host nation's choice, and
            that surface is published on each MATCH of the tie instead. The
            upstream field for those rows carries the DRAW TIER rather than a
            surface ("- Preliminary", "- Play Offs", "- Promotion"), and a value
            that is not one of hard/clay/grass is rejected rather than published.
            3 are the exhibition catch-all and 23 are ordinary events the
            upstream catalogue simply never stated a surface for.
        indoor: { type: boolean }
        city:
          type: [string, "null"]
          description: Host city, from a curated table — null where not curated.
        country:
          type: [string, "null"]
          description: >-
            Host country, ISO-3166 alpha-2 — null where not curated. (NOTE
            this differs from `player.country` and the `?country=` filter,
            which use IOC-style lowercase 3-letter codes.)
        category:
          type: [string, "null"]
          enum: [grand_slam, masters_1000, tour_finals, atp_500, atp_250,
                 wta_1000, wta_500, wta_250, wta_125, challenger, itf,
                 juniors, null]
          description: >-
            Tournament category where our catalogues agree unambiguously on an
            exact-name join — null otherwise, never derived from the name.
            Unchanged by `tier` (2026-09-22) and remains the coarse class;
            read `tier` for the level.
        tier:
          type: [string, "null"]
          enum:
            - grand_slam
            - atp_finals
            - atp_1000
            - atp_500
            - atp_250
            - next_gen_finals
            - united_cup
            - davis_cup
            - olympics
            - laver_cup
            - wta_finals
            - wta_elite_trophy
            - wta_1000
            - wta_500
            - wta_250
            - wta_125
            - bjk_cup
            - challenger_175
            - challenger_125
            - challenger_100
            - challenger_75
            - challenger_50
            - itf_m15
            - itf_m25
            - itf_w15
            - itf_w25
            - itf_w35
            - itf_w40
            - itf_w50
            - itf_w60
            - itf_w75
            - itf_w80
            - itf_w100
            - juniors
            - utr
            - exhibition
            - null
          description: >-
            The level this tournament is played at in the CURRENT season
            (added 2026-09-22) — the same closed vocabulary as `tier` on a
            match (`grand_slam`, `atp_1000` … `atp_250`, `wta_1000` …
            `wta_125`, `challenger_175` … `challenger_50`, `itf_m15` /
            `itf_m25`, `itf_w15` … `itf_w100`, the team events, `juniors`,
            `utr`, `exhibition`). A catalogue row has no season of its own; a
            match does: the tier is PER SEASON and it moves under one id —
            Dallas was `atp_250` in 2023 and 2024 and `atp_500` from 2025;
            Estoril `atp_250`, then `challenger_175` in 2025, then `atp_250`
            again in 2026; Eastbourne `wta_500` through 2024 and `wta_250`
            from 2025 — so read the tier off each MATCH for its season, never
            copy this value onto a match. Null when this season's calendar
            does not list the event — never guessed.
        tier_source:
          type: [string, "null"]
          enum: [calendar, name, wikipedia, resolver, null]
          description: >-
            How `tier` was established (added 2026-09-22): `calendar` = the
            official per-season tour calendar named the level (ATP tour and
            Challenger calendars, the WTA tournament list); `name` = an
            unambiguous name rule (the ITF category is in the event's official
            name — `M25 …`, `W35 …` — team and UTR events are named as such,
            and the Slam junior draws and exhibitions are their own event
            type); `wikipedia` = the season's schedule page, used only where
            the official calendar could not state the level for that season
            (Eastbourne 2023–2025); `resolver` = resolved after the seed
            dataset, by the same rules, from the event's name, tour and dates
            in that season. Null exactly when `tier` is null.
    ArchiveMatch:
      type: object
      description: >-
        One result of the results archive (1968–2022). Winner/loser-shaped —
        results data is recorded that way at the source, so the winner is a
        field, never an inference. Its own id space; `source_id` is the
        stable corpus key. A result played 2013–2022 may additionally carry a
        reconstructed point-by-point tape (`ArchiveTape`); results from
        1968–2012 have none and never will.
      properties:
        id: { type: integer }
        source_id: { type: string }
        tour: { type: string, enum: [atp, wta] }
        level:
          type: [string, "null"]
          description: >-
            Source tier code (G/M/A/F/D/C/O, or a futures category code as
            published).
        tournament: { type: [string, "null"] }
        surface: { type: [string, "null"] }
        draw_size: { type: [integer, "null"] }
        event_date:
          type: [string, "null"]
          format: date
          description: >-
            Tournament START date — per-match dates do not exist in this
            era's records, and we do not invent them.
        round: { type: [string, "null"] }
        best_of: { type: [integer, "null"] }
        minutes: { type: [integer, "null"] }
        winner: { $ref: "#/components/schemas/ArchivePlayer" }
        loser: { $ref: "#/components/schemas/ArchivePlayer" }
        score:
          type: [string, "null"]
          description: >-
            The final score as published, e.g. "6-4 7-6(5)", "6-3 RET",
            "W/O".
        outcome:
          type: [string, "null"]
          enum: [completed, retired, walkover, default, abandoned, null]
          description: >-
            Parsed from the score's own vocabulary; null when unparseable —
            never guessed.
        stats:
          type: [object, "null"]
          description: >-
            Detail endpoint only. {"winner":{...}, "loser":{...}} with aces,
            double_faults, serve_points, first_in, first_won, second_won,
            serve_games, bp_saved, bp_faced where the source recorded them;
            null otherwise (most rows before 1991) — never synthesised.
    ArchivePlayer:
      type: object
      description: One participant of an archive result, as the corpus records them.
      properties:
        name: { type: [string, "null"] }
        hand: { type: [string, "null"] }
        country:
          type: [string, "null"]
          description: 3-letter code, same vocabulary as `player.country`.
        rank:
          type: [integer, "null"]
          description: The player's rank AT THE TIME of the match, as published.
        seed: { type: [integer, "null"] }
        player_id:
          type: [integer, "null"]
          description: >-
            The corpus person id — joins `/history/archive/players` within
            the same tour. NOT a roster player id.
        height_cm: { type: [integer, "null"] }
        age:
          type: [number, "null"]
          description: Age at the time of the match, as the corpus records it.
        entry:
          type: [string, "null"]
          description: >-
            Draw entry where recorded (WC, Q, LL, PR, SE, ...) — null for
            direct acceptances.
    ArchivePlayerBio:
      type: object
      description: >-
        One archive person — own id space (the corpus person id that archive
        match rows carry as `winner.player_id` / `loser.player_id`, scoped
        per tour), never a roster id. Career-high is computed offline from
        the corpus's own weekly ranking tables at ingest, never modelled.
        Null fields are the era's silence.
      properties:
        id: { type: integer }
        tour: { type: string, enum: [atp, wta] }
        name: { type: [string, "null"] }
        hand: { type: [string, "null"] }
        dob: { type: [string, "null"], format: date }
        country: { type: [string, "null"] }
        height_cm: { type: [integer, "null"] }
        career_high_rank: { type: [integer, "null"] }
        career_high_date:
          type: [string, "null"]
          format: date
          description: The earliest week the career-high rank was reached.
    ArchiveCareer:
      type: object
      description: >-
        Career aggregates over the results archive (1968–2022) — sums and
        ratios of sums only, nothing modelled. Serve stats exist in the
        corpus from 1991; `serve.matches_with_stats` states the coverage.
      properties:
        player:
          type: object
          properties:
            name: { type: string }
        span:
          type: object
          properties:
            first: { type: [string, "null"] }
            last: { type: [string, "null"] }
        record:
          type: object
          properties:
            wins: { type: integer }
            losses: { type: integer }
            titles:
              type: integer
              description: Finals won (excluding abandoned finals).
            by_surface:
              type: object
              additionalProperties:
                type: object
                properties:
                  wins: { type: integer }
                  losses: { type: integer }
            by_level:
              type: object
              additionalProperties:
                type: object
                properties:
                  wins: { type: integer }
                  losses: { type: integer }
        by_year:
          type: array
          items:
            type: object
            properties:
              year: { type: integer }
              wins: { type: integer }
              losses: { type: integer }
        serve:
          type: object
          description: >-
            Summed serve statistics + derived ratios; null ratios where the
            denominator is zero.
          properties:
            matches_with_stats: { type: integer }
            aces: { type: integer }
            double_faults: { type: integer }
            serve_points: { type: integer }
            first_in: { type: integer }
            first_won: { type: integer }
            second_won: { type: integer }
            serve_games: { type: integer }
            bp_saved: { type: integer }
            bp_faced: { type: integer }
            first_in_pct: { type: [number, "null"] }
            first_won_pct: { type: [number, "null"] }
            second_won_pct: { type: [number, "null"] }
            bp_saved_pct: { type: [number, "null"] }
            aces_per_match: { type: [number, "null"] }
    ArchiveTape:
      type: object
      description: >-
        The reconstructed 2013-2022 point-by-point tape for one archive result.
        Same envelope as HistoryTape so one parser reads both halves of the tape
        product, with the differences that are TRUE: `match` is the archive
        result row (winner/loser-shaped), `profiles` is always empty, and every
        row carries a null `timestamp`, a null `age_seconds` and null model fields
        because nobody watched these matches and no model scored them. `meta` has
        no `match_id` — an archive id is not a match id.
      properties:
        match:
          $ref: '#/components/schemas/ArchiveMatch'
        tape:
          type: array
          description: The score sequence in seq order, WINNER-FIRST (`sets[0]` /
            `games[0]` / `points[0]` are the winner's, and a `server` of 1 means the winner
            was serving) — see HistoryTapeRow. `point_winner` and `winner` (since
            2026-09-22) are present; on a per-GAME tape, where consecutive rows differ
            by a whole game, each reads the side whose game count rose (the game point
            was theirs) and says nothing about the other points of that game.
          items:
            $ref: '#/components/schemas/HistoryTapeRow'
        tiebreaks:
          type:
          - array
          - 'null'
          description: Per-set tiebreak final scores, same rule and shape as on
            HistoryTape. Usually PRESENT even on a per-game tape — the pre-2023 record
            expands points inside tiebreaks even where it does not elsewhere.
          items:
            type:
            - object
            - 'null'
            properties:
              p1:
                type: integer
              p2:
                type: integer
        profiles:
          type: array
          description: Always empty. The key is kept so the envelope matches HistoryTape;
            no model analysis exists, or could exist, for a pre-2023 match.
          items:
            type: object
        meta:
          type: object
          properties:
            archive_match_id:
              type: integer
              description: The `archive_matches.id` this tape belongs to. Named in full
                because it is NOT a match id — passing it to a `/matches/...` route
                resolves a different, real record without erroring.
            tiebreaks_source:
              type:
              - array
              - 'null'
              description: Aligned to `tiebreaks`, same contract as on HistoryTape.
                Every populated entry here reads `reconstruction` — the archive
                tape IS the reconstruction and nothing else is consulted.
              items:
                type:
                - string
                - 'null'
            rows:
              type: integer
              description: Rows returned. Read next to `granularity` before comparing it
                with a 2023+ tape's row count. Across the corpus a tape averages 146 rows
                (median 138, range 4-570); a per-game tape carries one row per game and is
                far shorter than a point tape of the same match.
            coverage:
              type: string
              enum:
              - reconstructed
              - reconstructed_partial
              description: >-
                `reconstructed` (96.3% of the corpus) = the tape reproduces the
                published final score exactly, and that score is a match that
                finished. `reconstructed_partial` (3.7%) HAS TWO CAUSES and the
                label does not say which: either the match itself stopped early (a
                retirement or abandonment prefix), OR the tape is per-GAME — every
                one of the 556 game-granular tapes carries this label however
                complete it is, because the coverage vocabulary is closed and
                `game` has no word of its own. It therefore does NOT on its own
                mean incomplete match coverage: read `granularity` and the match's
                own score/outcome for that. Never `from_start` or `partial`: both
                assert we watched the match, and nobody watched these. On the 2023+
                tape the same word means only short-at-either-end.
            granularity:
              type: string
              enum:
              - point
              - game
              description: >-
                What one row resolves to. `point` = the record advances within a
                game — 99.4% of the corpus (97,293 matches). `game` = one row per
                game, with points expanded only inside tiebreaks — 556 matches, 555
                of them in 2013 and one in 2014; every season from 2015 on is 100%
                point-granular. `point_winner` / `winner` on a per-game tape read the
                side whose game count rose on each row, and nothing about the game's
                other points.
                Orthogonal to `coverage` as an axis, though a `game` tape is always
                labelled `reconstructed_partial`.
            point_source:
              type: string
              enum:
              - reconstructed
              description: Always `reconstructed`. It is a property of the dataset, not a
                measurement of these rows, and there is no other value it can take.
            model_rows:
              type: integer
              description: Always 0 — no model output exists for a pre-2023 match. Present
                so a client parsing both halves of the tape product reads one shape.
            observed_rows:
              type: integer
              description: Always 0 — no row here was watched live.
            point_source_detail:
              type: string
              description: 'Always `reconstruction from public record`. Stated in the
                payload so the provenance travels with the data rather than living only
                in a customer''s memory of these docs.'
            sequence:
              type: string
              enum:
              - raw
              description: Always `raw`. There is nothing to collapse — a reconstructed
                tape has one source and no corrections, so `?sequence=clean` has no
                meaning here; the parameter is ignored, not refused.
            generated_at:
              type: string
              format: date-time
    HeadToHead:
      type: object
      description: >-
        The record between two players across both halves of the product —
        the results archive (1968–2022) and our own completed matches
        (2023→now). Totals count meetings with a KNOWN winner; `undecided`
        counts the rest.
      properties:
        players:
          type: [object, "null"]
          description: >-
            The resolved names ({"p1":{"name"}, "p2":{"name"}}); null when no
            player matches the fragments.
        totals:
          type: object
          properties:
            p1_wins: { type: integer }
            p2_wins: { type: integer }
            meetings: { type: integer }
            undecided:
              type: integer
              description: >-
                Meetings with no derivable winner (never counted in wins).
        by_surface:
          type: object
          description: >-
            Per-surface win split of the decided meetings; keys are surface
            names plus 'unknown'.
          additionalProperties:
            type: object
            properties:
              p1: { type: integer }
              p2: { type: integer }
        meetings:
          type: array
          description: >-
            Newest first, capped at 200. `era` says which half served the
            row — 'archive' rows carry `archive_match_id`/`level`/`score`;
            'current' rows carry `match_id`/`round_code` and read their score
            from the match endpoints. `winner` is 1|2 OF THIS H2H (p1/p2 as
            requested), null when underivable.
          items:
            type: object
            properties:
              era: { type: string, enum: [archive, current] }
              date: { type: [string, "null"] }
              tournament: { type: [string, "null"] }
              level: { type: [string, "null"] }
              round: { type: [string, "null"] }
              surface: { type: [string, "null"] }
              score: { type: [string, "null"] }
              outcome: { type: [string, "null"] }
              winner: { type: [integer, "null"] }
        stats:
          type: [object, "null"]
          description: >-
            ULTRA only — per-player serve/return/break-point aggregates over
            the pairing, keyed `p1`/`p2`. Each side carries `archive_serve`
            (serve-side figures, meetings from 1991) and `current` (2023+,
            adding return and break-point conversion, aces and winners), each
            with its own `meetings_with_stats` sample size. Absent below ULTRA.
    RallyMatch:
      type: object
      description: >-
        One charted match of the rally-construction corpus — its own id
        space, keyed on `rally_match_id`.
      properties:
        rally_match_id:
          type: integer
          description: The id this product is keyed on.
        source_id: { type: string }
        match_id:
          type: [integer, "null"]
          description: >-
            OUR match id, when the charted match is also one we hold. Null
            otherwise — most charted matches predate our own collection.
        date: { type: [string, "null"], format: date }
        tournament: { type: [string, "null"] }
        round: { type: [string, "null"] }
        surface: { type: [string, "null"] }
        gender: { type: [string, "null"], enum: [M, W, null] }
        best_of: { type: [integer, "null"] }
        players:
          type: array
          maxItems: 2
          items:
            type: object
            properties:
              name: { type: [string, "null"] }
              hand: { type: [string, "null"], enum: [R, L, U, A, null] }
        points:
          type: integer
          description: Charted points in this match.
        points_parsed:
          type: integer
          description: >-
            How many of them our parser read cleanly — the per-match quality
            number.
    RallyPoint:
      type: object
      description: >-
        One charted point. `raw` is the charter's own string, verbatim, and
        is ALWAYS present; the parsed fields are our reading of it. `parsed`
        is false when the notation contained something we could not read
        cleanly — the recognised part is still returned. A consumer who wants
        only unambiguous rows filters on `parsed`.
      properties:
        point: { type: integer }
        set:
          type: array
          items: { type: [integer, "null"] }
          maxItems: 2
        games:
          type: array
          items: { type: [integer, "null"] }
          maxItems: 2
        score:
          type: [string, "null"]
          description: e.g. '30-40'.
        game: { type: [integer, "null"] }
        is_tiebreak: { type: boolean }
        server: { type: [integer, "null"], enum: [1, 2, null] }
        point_winner: { type: [integer, "null"], enum: [1, 2, null] }
        raw:
          type: [string, "null"]
          description: >-
            The charter's shot string; both serves joined by ';' when the
            first was a fault.
        parsed: { type: boolean }
        serve_number: { type: [integer, "null"], enum: [1, 2, null] }
        serve_direction:
          type: [string, "null"]
          enum: [wide, body, down_the_t, null]
        rally_length:
          type: [integer, "null"]
          description: >-
            Strokes including the serve. An ace is 1, a double fault 0.
        outcome:
          type: [string, "null"]
          enum: [winner, forced_error, unforced_error, error, other, null]
          description: >-
            `error` = the charter recorded a miss without saying whether it
            was forced. Never guessed.
        error_location:
          type: [string, "null"]
          enum: [net, wide, deep, wide_and_deep, null]
        ending_stroke: { type: [string, "null"] }
        ending_wing: { type: [string, "null"] }
        is_ace: { type: boolean }
        is_double_fault: { type: boolean }
        is_serve_and_volley: { type: boolean }
        is_unreturned:
          type: boolean
          description: >-
            Derived (added 2026-09-05). The server won the point without the
            returner putting the ball in play. A double fault is never
            unreturned.
        unreturned_kind:
          type: [string, "null"]
          enum: [ace, serve_winner, serve_forced_error, return_forced_error,
                 return_unforced_error, return_error, null]
          description: >-
            How the serve went unreturned. `serve_winner` is a serve winner
            charted without a direction code (so `is_ace` is unset) — count it
            with the aces. `return_error` = the return missed and the charter
            did not say whether it was forced. Null when the return was in play
            or the parse could not say.
        shots:
          type: array
          items: { $ref: "#/components/schemas/RallyShot" }
    RallyShot:
      type: object
      description: >-
        One stroke. Shots are numbered from the serve: serve 1, return 2, the
        server's next ball 3.
      properties:
        number: { type: integer }
        code:
          type: string
          description: The charter's raw code, e.g. 'f'.
        stroke:
          type: [string, "null"]
          enum: [serve, groundstroke, slice, volley, half_volley,
                 swinging_volley, overhead, drop_shot, lob, trick, unknown,
                 null]
        wing:
          type: [string, "null"]
          enum: [forehand, backhand, null]
          description: The side it was struck FROM.
        direction:
          type: [string, "null"]
          enum: [forehand_side, middle, backhand_side, null]
          description: Where the ball was sent.
        depth:
          type: [string, "null"]
          enum: [shallow, mid, deep, null]
        position:
          type: [string, "null"]
          enum: [approaching, at_net, baseline, null]