DataSportsAPI WebSocket API

openapi: 3.2.0
info:
  title: DataSports WebSocket API
  version: '2026-11-12'
  summary: Real-time sports data over REST for 24 sports — scores, schedules, lineups, match statistics, tables, and team, player and league profiles.
  description: 'One consistent JSON contract for 24 sports: fixtures and live scores, lineups and statistics, standings, plus teams, players and leagues, delivered in real time over REST, WebSocket and webhooks.


    Successful responses use a `{ data, meta? }` envelope; failures return `{ error: { code, message } }` under a matching HTTP status. All ids are DataSportsAPI ids. Each component schema documents its fields, units and enum values, as does the data reference (https://datasportsapi.com/markdown/reference.md). The WebSocket stream, webhooks and widgets are documented at https://datasportsapi.com/docs/.


    Availability: pre-launch. This documents the v2 contract; accounts, API keys and the SDK packages open with the public launch — until then, join the early-access list at https://datasportsapi.com/signup/. During the beta the Free plan allows 1,000 requests a day (100 a day after).'
  contact:
    name: DataSportsAPI
    email: contact@noventra.dev
    url: https://datasportsapi.com/contact/
servers:
- url: https://api.datasportsapi.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Websocket
  x-displayName: WebSocket
  description: WebSocket. Live deltas for scores and statuses. Obtain a single-use ticket via REST and then open the connection, so your API key never appears in a WebSocket URL. Offered on Business (three simultaneous connections per account) and Enterprise (five), with the tracking:{id} channel kept for Enterprise.
paths:
  /v2/stream/ticket:
    post:
      operationId: websocket.streamTicket
      tags:
      - Websocket
      summary: Stream ticket
      description: 'Issues a one-time ticket for opening a connection, valid for 30 seconds. The call is authenticated, rate-limited and counted against your usage exactly like any other /v2 request, and it takes no request body.


        **Plans:** Requires Business or Enterprise; on a lower plan the ticket request returns 403 ws_not_available. The tracking:{id} channel needs Enterprise and is refused on Business with channel_forbidden.'
      x-plans:
      - business
      - enterprise
      externalDocs:
        description: Docs page
        url: https://datasportsapi.com/docs/api/websocket/stream-ticket/
      parameters: []
      responses:
        '200':
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ticket:
                        type: string
                      url:
                        type: string
                        format: uri
                      expiresInSeconds:
                        type: integer
                    required:
                    - ticket
                    - url
                    - expiresInSeconds
                required:
                - data
        '400':
          description: 'Bad request (`bad_request`): the message lists the values the parameter accepts.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, unknown or revoked API key (`unauthorized`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '- ws_not_available — WebSocket access is not part of your plan


            Refused: your plan does not include this endpoint (`endpoint_not_in_plan`), the requested data predates your plan''s history window (`history_not_in_plan`; see `historyFrom`), or the caller''s IP is missing from the account''s allowlist (`ip_not_allowed`, Business and Enterprise).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found (`not_found`), valid ids with no source data behind them (`no_data`, e.g. tracking of a fixture the source does not follow), or an endpoint that does not cover this sport (`not_supported`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Per-minute rate exceeded (`rate_limited`) or the period's quota spent (`quota_exceeded`); wait the `Retry-After` seconds.
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Our fault (`internal_error`); safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Upstream data temporarily unavailable (`upstream_unavailable`); try again once the `Retry-After` seconds have passed.
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST -H \"Authorization: Bearer dsa_live_…\" \\\n    \"https://api.datasportsapi.com/v2/stream/ticket\""
components:
  schemas:
    Error:
      type: object
      description: The body of every failed request. Branch on error.code; the message may be reworded.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable, snake_case code, e.g. not_found. Part of the contract.
            message:
              type: string
              description: A readable sentence for logs; never parse it.
            historyFrom:
              type: string
              format: date
              description: 'history_not_in_plan only: the first day your plan can read.'
          required:
          - code
          - message
      required:
      - error
  headers:
    RateLimit-Limit:
      description: Your plan's request quota for the current period (UTC month on paid plans, UTC day on Free).
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before trying again.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests still available in the current period.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the period ends and the quota refills.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your secret API key: `Authorization: Bearer dsa_live_…`. Publishable widget keys (`dsa_pub_…`) work only for the endpoints widgets read, from the sites registered on them.'
externalDocs:
  description: Documentation
  url: https://datasportsapi.com/docs/