openapi: 3.0.0
info:
  title: Kalshi Trade API Manual Endpoints account live-data API
  version: 3.19.0
  description: Manually defined OpenAPI spec for endpoints being migrated to spec-first approach
servers:
- url: https://external-api.kalshi.com/trade-api/v2
  description: Production Trade API server
- url: https://api.elections.kalshi.com/trade-api/v2
  description: Production shared API server, also supported
- url: https://external-api.demo.kalshi.co/trade-api/v2
  description: Demo Trade API server
- url: https://demo-api.kalshi.co/trade-api/v2
  description: Demo shared API server, also supported
tags:
- name: live-data
  description: Live data endpoints
paths:
  /live_data/milestone/{milestone_id}:
    get:
      operationId: GetLiveDataByMilestone
      summary: Get Live Data
      description: Get live data for a specific milestone.
      tags:
      - live-data
      parameters:
      - name: milestone_id
        in: path
        required: true
        description: Milestone ID
        schema:
          type: string
      - name: include_player_stats
        in: query
        required: false
        description: When true, includes player-level statistics in the live data response. Supported for Pro Football, Pro Basketball, and College Men's Basketball milestones that have player ID mappings configured. Has no effect for other sports or milestones without player mappings.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Live data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLiveDataResponse'
        '404':
          description: Live data not found
        '500':
          description: Internal server error
  /live_data/{type}/milestone/{milestone_id}:
    get:
      operationId: GetLiveData
      summary: Get Live Data (with type)
      description: Get live data for a specific milestone. This is the legacy endpoint that requires a type path parameter. Prefer using `/live_data/milestone/{milestone_id}` instead.
      tags:
      - live-data
      parameters:
      - name: type
        in: path
        required: true
        description: Type of live data
        schema:
          type: string
      - name: milestone_id
        in: path
        required: true
        description: Milestone ID
        schema:
          type: string
      - name: include_player_stats
        in: query
        required: false
        description: When true, includes player-level statistics in the live data response. Supported for Pro Football, Pro Basketball, and College Men's Basketball milestones that have player ID mappings configured. Has no effect for other sports or milestones without player mappings.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Live data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLiveDataResponse'
        '404':
          description: Live data not found
        '500':
          description: Internal server error
  /live_data/batch:
    get:
      operationId: GetLiveDatas
      summary: Get Multiple Live Data
      description: Get live data for multiple milestones
      tags:
      - live-data
      parameters:
      - name: milestone_ids
        in: query
        required: true
        description: Array of milestone IDs
        schema:
          type: array
          items:
            type: string
          maxItems: 100
        style: form
        explode: true
      - name: include_player_stats
        in: query
        required: false
        description: When true, includes player-level statistics in the live data response. Supported for Pro Football, Pro Basketball, and College Men's Basketball milestones that have player ID mappings configured. Has no effect for other sports or milestones without player mappings.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Live data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLiveDatasResponse'
        '500':
          description: Internal server error
  /live_data/milestone/{milestone_id}/game_stats:
    get:
      operationId: GetGameStats
      summary: Get Game Stats
      description: 'Get play-by-play game statistics for a specific milestone. Supported sports: Pro Football, College Football, Pro Basketball, College Men''s Basketball, College Women''s Basketball, WNBA, Soccer, Pro Hockey, and Pro Baseball. Returns null for unsupported milestone types or milestones without a Sportradar ID.'
      tags:
      - live-data
      parameters:
      - name: milestone_id
        in: path
        required: true
        description: Milestone ID
        schema:
          type: string
      responses:
        '200':
          description: Game stats retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGameStatsResponse'
        '404':
          description: Game stats not found
        '500':
          description: Internal server error
components:
  schemas:
    GetLiveDatasResponse:
      type: object
      required:
      - live_datas
      properties:
        live_datas:
          type: array
          items:
            $ref: '#/components/schemas/LiveData'
    PlayByPlay:
      type: object
      description: Play-by-play data organized by period.
      properties:
        periods:
          type: array
          items:
            type: object
            properties:
              events:
                type: array
                items:
                  type: object
                  additionalProperties: true
    GetGameStatsResponse:
      type: object
      properties:
        pbp:
          $ref: '#/components/schemas/PlayByPlay'
    GetLiveDataResponse:
      type: object
      required:
      - live_data
      properties:
        live_data:
          $ref: '#/components/schemas/LiveData'
    LiveData:
      type: object
      required:
      - type
      - details
      - milestone_id
      properties:
        type:
          type: string
          description: Type of live data
        details:
          type: object
          additionalProperties: true
          description: Live data details as a flexible object
        milestone_id:
          type: string
          description: Milestone ID
  securitySchemes:
    kalshiAccessKey:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-KEY
      description: Your API key ID
    kalshiAccessSignature:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-SIGNATURE
      description: RSA-PSS signature of the request
    kalshiAccessTimestamp:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-TIMESTAMP
      description: Request timestamp in milliseconds