Live Tennis API Ws Token API

openapi: 3.2.0
info:
  title: Live Tennis Ws Token API
  version: 1.13.76
  contact:
    name: Live Tennis API
    url: https://livetennisapi.com
  license:
    name: MIT
    identifier: MIT
  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`), the

    rank-ordered rankings listing (`/rankings?system=`) and one player''s

    win/loss and set-based record (`/players/{playerId}/stats`). 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`) and their

    per-player sums (`serve_return` on `/players/{playerId}/stats`), 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: reconstructed point sequences,

    no capture timestamps. 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 we hold no point sequence for those years 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.'
servers:
- url: https://api.livetennisapi.com/api/public/v1
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Ws Token
paths:
  /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": ""}, "id": 1}` — the token goes INSIDE this JSON frame, never as a raw first message; (3) subscribe per channel with `{"subscribe": {"channel": "slate:all"}, "id": 2}`; (4) publications arrive as `{"push": {"channel": ..., "pub": {"data": }}}`; (5) the server''s heartbeat is an empty JSON object `{}` — reply with `{}` promptly or you will be disconnected. Messages may batch several newline-delimited JSON objects. Tokens are short-lived and the connection closes around token expiry: mint a fresh token on EVERY reconnect and re-subscribe. 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.'
      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'
      tags:
      - Ws Token
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Stable machine-readable code, e.g. bad_date, bad_coverage, bad_sequence, bad_points, bad_points_complete, bad_combination, points_read_disabled, bad_after_seq, 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).
  responses:
    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'
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Direct API key: Authorization: Bearer <key>'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key