Sportradar NFL Push API

openapi: 3.2.0
info:
  title: Sportradar Push Feeds NFL Push API
  description: Sportradar's Push Feeds deliver real-time sports data over HTTP using chunked transfer encoding.
  version: v1
  contact:
    name: Sportradar Developer Support
    url: https://developer.sportradar.com/docs/read/Home#support
  termsOfService: https://sportradar.com/terms/
servers:
- url: https://api.sportradar.com
  description: Sportradar Push Feeds Production Server
security:
- apiKey: []
tags:
- name: NFL Push
  description: NFL Push Feeds deliver real-time game events, statistics, pulse messages, and draft activity over HTTP chunked streaming.
  externalDocs:
    url: https://developer.sportradar.com/football/docs/nfl-ig-push
paths:
  /nfl/official/{access_level}/stream/{language_code}/events/subscribe:
    get:
      operationId: subscribeNflPushEvents
      summary: Subscribe to NFL Push Events
      description: Opens a long-lived HTTP chunked connection that streams real-time information on every live NFL game event as it occurs. Events include scoring plays, drive updates, and other on-field activity. Heartbeat messages are sent every five seconds when no new events are available. Use the optional match filter to limit the stream to a single game.
      tags:
      - NFL Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/languageCodeParam'
      - $ref: '#/components/parameters/matchFilterParam'
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
  /nfl/official/{access_level}/stream/{language_code}/statistics/subscribe:
    get:
      operationId: subscribeNflPushStatistics
      summary: Subscribe to NFL Push Statistics
      description: Opens a long-lived HTTP chunked connection that streams detailed, real-time game statistics at the team and player level. Heartbeat messages are sent every five seconds when no new statistics are available.
      tags:
      - NFL Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/languageCodeParam'
      - $ref: '#/components/parameters/matchFilterParam'
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
  /nfl/official/{access_level}/stream/{language_code}/pulse/subscribe:
    get:
      operationId: subscribeNflPushPulse
      summary: Subscribe to NFL Push Pulse
      description: Opens a long-lived HTTP chunked connection that streams real-time pulse messages describing on-field activity. Heartbeat messages are sent every five seconds when no new content is available.
      tags:
      - NFL Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/languageCodeParam'
      - $ref: '#/components/parameters/matchFilterParam'
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
  /nfl/official/{access_level}/stream/{language_code}/draft-picks/subscribe:
    get:
      operationId: subscribeNflPushDraftPicks
      summary: Subscribe to NFL Push Draft Picks
      description: Opens a long-lived HTTP chunked connection that streams real-time NFL draft pick selections as they occur. Heartbeat messages are sent every five seconds when no new picks are available.
      tags:
      - NFL Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/languageCodeParam'
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
  /nfl/official/{access_level}/stream/{language_code}/draft-trades/subscribe:
    get:
      operationId: subscribeNflPushDraftTrades
      summary: Subscribe to NFL Push Draft Trades
      description: Opens a long-lived HTTP chunked connection that streams summary details of all in-draft trades in real-time. Heartbeat messages are sent every five seconds when no new trades are available.
      tags:
      - NFL Push
      parameters:
      - $ref: '#/components/parameters/accessLevelParam'
      - $ref: '#/components/parameters/languageCodeParam'
      responses:
        '200':
          $ref: '#/components/responses/PushStream'
        '302':
          $ref: '#/components/responses/PushRedirect'
        '401':
          description: Unauthorized - invalid or missing API key.
        '403':
          description: Forbidden - account is not entitled to Realtime push feeds.
components:
  parameters:
    accessLevelParam:
      name: access_level
      in: path
      required: true
      description: Sportradar access level for the requested package. Trial accounts use 'trial'; production customers use 'production'.
      schema:
        type: string
        enum:
        - trial
        - production
    languageCodeParam:
      name: language_code
      in: path
      required: true
      description: Two-letter language code controlling localized text in the feed (for example, 'en' for English).
      schema:
        type: string
    matchFilterParam:
      name: match
      in: query
      required: false
      description: Optional filter that restricts the stream to a single game. Provide the fully qualified Sportradar match identifier (for example, sd:match:b9cf745b-36a1-404e-8159-78d719742a6b).
      schema:
        type: string
  responses:
    PushRedirect:
      description: Push Feed subscriptions begin with an HTTP redirect to the streaming origin. Clients must follow the redirect within one minute of the initial request.
      headers:
        Location:
          description: URL of the streaming origin to follow.
          schema:
            type: string
            format: uri
    PushStream:
      description: Successful subscription. The server returns an open HTTP connection with Transfer-Encoding chunked and continuously emits JSON messages. Heartbeat messages are emitted every five seconds when no other content is available.
      headers:
        Transfer-Encoding:
          description: Always 'chunked' for Push Feed responses.
          schema:
            type: string
            enum:
            - chunked
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Heartbeat'
            - $ref: '#/components/schemas/PushPayload'
  schemas:
    PushPayload:
      type: object
      description: Generic envelope describing a Push Feed payload. Each Sportradar package defines the concrete metadata and payload shape; refer to the package-specific documentation for field-level details.
      properties:
        metadata:
          type: object
          description: Feed metadata describing the package, sport, event, and sequence information for the message.
          additionalProperties: true
        payload:
          type: object
          description: Package-specific payload such as an event, statistics update, clock update, or draft activity.
          additionalProperties: true
    Heartbeat:
      type: object
      description: Heartbeat message emitted every five seconds when no new content is available on the stream. Used by clients to confirm the connection is still healthy.
      properties:
        heartbeat:
          type: object
          properties:
            from:
              type: integer
              description: Start of the heartbeat window as a Unix timestamp.
            to:
              type: integer
              description: End of the heartbeat window as a Unix timestamp.
            interval:
              type: integer
              description: Heartbeat interval in seconds.
              examples:
              - 5
            type:
              type: string
              description: Feed type the heartbeat is associated with.
              examples:
              - events
              - statistics
              - clock
              - pulse
            package:
              type: string
              description: Sportradar package emitting the heartbeat.
              examples:
              - soccer-v4
              - nfl
              - nba
              - nhl
              - wnba
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Sportradar Push Feeds require an API key passed in the x-api-key request header. Push entitlements are tied to Realtime customer accounts.
externalDocs:
  description: Sportradar Push Feeds Documentation
  url: https://developer.sportradar.com/getting-started/docs/get-started