SportStatsAPI Changes API

openapi: 3.2.0
info:
  contact:
    name: SportStatsAPI
    url: https://sportstatsapi.com
  description: 'Every public endpoint of SportStatsAPI. Endpoints marked with x-x402 can also be paid per call by an AI agent; the curated list of those is https://api.sportstatsapi.com/api/openapi.agents.json.


    Authentication: an API key (header X-API-Key, or Authorization: Bearer ), or without a key an x402 payment (header PAYMENT-SIGNATURE, USDC on Base). Prices and payment offers: https://api.sportstatsapi.com/.well-known/x402. Docs for AI models: https://api.sportstatsapi.com/llms.txt. MCP server: https://mcp.sportstatsapi.com/mcp.'
  summary: Sports data API and x402 pay-per-call endpoints
  title: SportStats Changes API
  version: '1.0'
servers:
- url: https://api.sportstatsapi.com/api/v1
tags:
- name: Changes
paths:
  /changes:
    get:
      description: 'Finished matches whose final score or stored statistics (soccer: per player minutes, starter or substitute, goals, penalty and own goals, assists, cards, saves and goals conceded, not ratings or other statistics, and only once a complete final row was stored; NBA, MLB, NHL, NFL and other basketball, baseball, hockey and American football: the player game lines of /{sport}/players/{id}/games, once a final box score with both teams'' players was stored) changed after the match had its result, oldest change first, so fantasy and betting apps can re-score them. A match is listed once, at its latest change; score_changed_at and stats_changed_at say what changed. The match is shown as stored now; read /{sport}/matches/{id} and /{sport}/matches/{id}/stats for the new numbers. Changes made before a match was final are not listed, nor are matches first stored with their result. Tennis, handball and volleyball, and box scores without player ids: score changes only. Changes of the last minute wait for the next call. Start with since (RFC 3339), then pass meta.next_cursor as cursor; meta.has_more says to ask again at once (a page can be empty for a league-pack key and still have more); an empty last page keeps the same next_cursor, so a poller stores it and asks again later. Only changes since this feed was released are listed (no history before it).'
      operationId: getChanges
      parameters:
      - description: soccer, basketball, baseball, hockey, handball, volleyball, american-football or tennis
        in: query
        name: sport
        required: true
        schema:
          type: string
      - description: Changes after this time (RFC 3339); needed without cursor
        in: query
        name: since
        schema:
          type: string
      - description: meta.next_cursor of the previous page
        in: query
        name: cursor
        schema:
          type: string
      - description: Matches (1-500, default 100)
        in: query
        name: limit
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    data:
                      items:
                        $ref: '#/components/schemas/dto.MatchChangeResponse'
                      type: array
                    meta:
                      $ref: '#/components/schemas/middleware.MetaInfo'
                  type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/middleware.Response'
                - properties:
                    error:
                      $ref: '#/components/schemas/middleware.ErrorInfo'
                  type: object
          description: Forbidden
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      summary: 'Stat corrections: finished matches that changed'
      tags:
      - Changes
components:
  schemas:
    dto.MatchChangeResponse:
      properties:
        away_team:
          $ref: '#/components/schemas/dto.TeamInfo'
        changed_at:
          description: the latest change (UTC)
          type: string
        date:
          type: string
        home_team:
          $ref: '#/components/schemas/dto.TeamInfo'
        league_id:
          type: integer
        league_name:
          type: string
        match_id:
          type: integer
        score_changed_at:
          description: the latest score change
          type: string
        static_id:
          description: 'soccer: the match''s code when it has no match id'
          type: integer
        stats_changed_at:
          description: the latest statistics or box score change
          type: string
        status:
          type: string
      type: object
    dto.TeamInfo:
      properties:
        display_name:
          description: 'DisplayName: the name to show (accents and case from official sources; a managed club''s own name), else name. name stays the data provider''s: filters match on it.'
          type: string
        id:
          type: integer
        name:
          type: string
        score:
          type: integer
      type: object
    middleware.Response:
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/middleware.ErrorInfo'
        meta:
          $ref: '#/components/schemas/middleware.MetaInfo'
        success:
          type: boolean
      type: object
    middleware.MetaInfo:
      properties:
        attribution:
          description: Attribution a data source's licence asks for (Cricsheet's history).
          type: string
        has_more:
          description: 'HasMore: the cursor-paged list has more rows now (ask again at once).'
          type: boolean
        limit:
          type: integer
        live:
          description: 'Live: the answer is the live feed''s, kept while the match is played

            (cricket ball by ball before Cricsheet''s file replaces it).'
          type: boolean
        next_cursor:
          description: NextCursor continues a cursor-paged list (GET /changes).
          type: string
        offset:
          type: integer
        sources:
          description: 'Sources: where the answer''s data came from, with each source''s licence

            and the attribution it asks for (docs/source-licences.md).'
          items:
            $ref: '#/components/schemas/middleware.SourceInfo'
          type: array
        total:
          type: integer
        warnings:
          description: 'Warnings: query parameters ignored or changed (a limit above the

            maximum is clamped to it; a from/to that is not a date is ignored).'
          items:
            type: string
          type: array
      type: object
    middleware.SourceInfo:
      properties:
        attribution:
          description: show it with the data
          example: 'Data: nflverse (CC-BY 4.0)'
          type: string
        licence:
          description: the licence or terms the data is served under
          example: CC-BY-4.0
          type: string
        name:
          description: provider = our main licensed feed
          example: nflverse
          type: string
      type: object
    middleware.ErrorInfo:
      properties:
        code:
          type: string
        message:
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: The same API key as a bearer token
      scheme: bearer
      type: http
    x402:
      description: x402 v2 payment (USDC on Base, eip155:8453) built from the offers of a 402 answer; see https://api.sportstatsapi.com/.well-known/x402
      in: header
      name: PAYMENT-SIGNATURE
      type: apiKey
externalDocs:
  description: x402 payment offers and prices
  url: https://api.sportstatsapi.com/.well-known/x402