realtimesportsapi-com Athletes API

openapi: 3.2.0
info:
  title: Realtimesportsapi Com Athletes API
  version: 1.0.0
  contact:
    name: Realtime Sports API support
    email: austin@elcodev.com
    url: https://www.realtimesportsapi.com/?utm_source=openapi
  license:
    name: Proprietary
    url: https://www.realtimesportsapi.com/terms?utm_source=openapi
  termsOfService: https://www.realtimesportsapi.com/terms?utm_source=openapi
  description: 'Operations tagged Athletes across 2 of this provider''s published API definitions: original.json, realtimesportsapi-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.realtimesportsapi.com/api/v1
  description: Production
security:
- BearerAuth: []
- ApiKeyHeader: []
tags:
- name: Athletes
  description: Athletes, search, game logs and availability history
paths:
  /sports/{sport}/leagues/{league}/athletes:
    get:
      operationId: listAthletes
      tags:
      - Athletes
      summary: List athletes
      description: Paginated. Some leagues have tens of thousands of athletes; prefer team rosters or search.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: limit
        in: query
        required: false
        description: Maximum athletes to return (default 25).
        schema:
          type: integer
          example: 25
          default: 25
          minimum: 1
      - name: page
        in: query
        required: false
        description: Page number (1-based).
        schema:
          type: integer
          example: 1
          default: 1
          minimum: 1
      - name: include
        in: query
        required: false
        description: Pass `statistics` to attach stats to each athlete (slower).
        schema:
          type: string
          example: statistics
          enum:
          - statistics
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Athlete'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/athletes/search:
    get:
      operationId: searchAthletes
      tags:
      - Athletes
      summary: Search athletes by name
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: query
        in: query
        required: true
        description: Name to search for (`q` is accepted as an alias).
        schema:
          type: string
          example: mahomes
      - name: limit
        in: query
        required: false
        description: Maximum results to return (default 25).
        schema:
          type: integer
          example: 25
          default: 25
          minimum: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AthleteSearchResult'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                      query:
                        type: string
                      count:
                        type: integer
                required:
                - success
                - data
        '400':
          description: query parameter is required (MISSING_QUERY).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/athletes/{athleteId}:
    get:
      operationId: getAthlete
      tags:
      - Athletes
      summary: Get an athlete
      description: Athlete profile with statistics. Omit season for career/current totals.
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: athleteId
        in: path
        required: true
        description: Athlete id, as returned by the athletes endpoints.
        schema:
          type: string
          example: '3139477'
      - name: season
        in: query
        required: false
        description: Scope statistics to a season year.
        schema:
          type: integer
          example: 2025
      - name: seasonType
        in: query
        required: false
        description: 1 = preseason, 2 = regular season, 3 = postseason. `type` is accepted as an alias.
        schema:
          type: integer
          example: 2
          enum:
          - 1
          - 2
          - 3
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Athlete'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Athlete not found (ATHLETE_NOT_FOUND).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/athletes/{athleteId}/gamelog:
    get:
      operationId: getAthleteGameLog
      tags:
      - Athletes
      summary: Get athlete game log
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: athleteId
        in: path
        required: true
        description: Athlete id, as returned by the athletes endpoints.
        schema:
          type: string
          example: '3139477'
      - name: season
        in: query
        required: true
        description: Season year.
        schema:
          type: integer
          example: 2026
      - name: week
        in: query
        required: false
        description: Only this week.
        schema:
          type: integer
          example: 5
      - name: seasonType
        in: query
        required: false
        description: 1 = preseason, 2 = regular season, 3 = postseason. `type` is accepted as an alias.
        schema:
          type: integer
          example: 2
          enum:
          - 1
          - 2
          - 3
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GameLogEntry'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                      season:
                        type: string
                        example: '2025'
                      count:
                        type: integer
                required:
                - success
                - data
        '400':
          description: season query parameter is required (MISSING_SEASON).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
  /sports/{sport}/leagues/{league}/athletes/{athleteId}/availability-history:
    get:
      operationId: getAthleteAvailabilityHistory
      tags:
      - Athletes
      summary: Get athlete availability history
      description: Time series of a player's injury/availability designations, newest first, as observed by our snapshots (every 5 minutes).
      parameters:
      - name: sport
        in: path
        required: true
        description: 'Sport slug: football, basketball, baseball, hockey, soccer.'
        schema:
          type: string
          example: football
      - name: league
        in: path
        required: true
        description: League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.
        schema:
          type: string
          example: nfl
      - name: athleteId
        in: path
        required: true
        description: Athlete id, as returned by the athletes endpoints.
        schema:
          type: string
          example: '3139477'
      - name: limit
        in: query
        required: false
        description: Maximum transitions to return (default 100, max 500).
        schema:
          type: integer
          example: 100
          default: 100
          minimum: 1
          maximum: 500
      - name: from
        in: query
        required: false
        description: Only items on or after this ISO-8601 timestamp.
        schema:
          type: string
          example: '2026-09-01T00:00:00Z'
          format: date-time
      - name: to
        in: query
        required: false
        description: Only items on or before this ISO-8601 timestamp.
        schema:
          type: string
          example: '2026-10-01T00:00:00Z'
          format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      athleteId:
                        type: string
                      current:
                        type:
                        - object
                        - 'null'
                        allOf:
                        - $ref: '#/components/schemas/AvailabilityState'
                      history:
                        type: array
                        items:
                          $ref: '#/components/schemas/AvailabilityTransition'
                  meta:
                    type: object
                    properties:
                      rateLimit:
                        $ref: '#/components/schemas/RateLimit'
                      count:
                        type: integer
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://www.realtimesportsapi.com/api/v1
      description: Production
components:
  schemas:
    GameLogEntry:
      type: object
      properties:
        eventId:
          type: string
        name:
          type: string
        shortName:
          type: string
        date:
          type: string
        week:
          type: integer
          example: 5
        seasonType:
          type: integer
          example: 2
        teamId:
          type: string
        played:
          type: boolean
          example: true
        statistics:
          type: object
          additionalProperties: true
    AvailabilityState:
      type: object
      properties:
        athleteId:
          type: string
        name:
          type: string
        position:
          type: string
        teamId:
          type: string
        teamName:
          type: string
        availability:
          type: string
          example: QUESTIONABLE
          enum:
          - OUT
          - DOUBTFUL
          - QUESTIONABLE
          - PROBABLE
          - DAY_TO_DAY
          - INJURED_RESERVE
          - SUSPENDED
          - AVAILABLE
          - UNKNOWN
        status:
          type: string
          example: Questionable
        reason:
          type: string
          example: Hamstring
        detail:
          type: string
        reportDate:
          type: string
        observedAt:
          type: string
          format: date-time
        injuryId:
          type: string
        returnDate:
          type: string
          example: '2026-10-18'
        practice:
          type: string
          example: LIMITED
          enum:
          - DNP
          - LIMITED
          - FULL
          description: Parsed from the news note (derived, not a structured provider field).
        practiceDay:
          type: string
          example: Wednesday
        seasonYear:
          type: integer
          example: 2026
        seasonType:
          type: integer
          example: 2
        week:
          type: integer
          example: 5
    Athlete:
      type: object
      properties:
        id:
          type: string
          example: '3139477'
        displayName:
          type: string
          example: Patrick Mahomes
        firstName:
          type: string
          example: Patrick
        lastName:
          type: string
          example: Mahomes
        position:
          type: string
          example: QB
        jersey:
          type: string
          example: '15'
        age:
          type: integer
          example: 31
        team:
          type: object
          properties:
            id:
              type: string
              example: '12'
            name:
              type: string
              example: Chiefs
        headshot:
          type: string
        hasStats:
          type: boolean
          example: true
        statistics:
          type: object
          properties:
            splits:
              type: object
              additionalProperties: true
          description: Present on the single-athlete endpoint, or on the list with include=statistics.
        statisticsScope:
          type: object
          properties:
            season:
              type: string
              example: '2025'
            seasonType:
              type:
              - integer
              - 'null'
              example: 2
    AthleteSearchResult:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        shortName:
          type: string
        jersey:
          type: string
        sport:
          type: string
          example: football
        league:
          type: string
          example: nfl
        image:
          type: string
        team:
          type: object
          properties:
            id:
              type: string
            displayName:
              type: string
            abbreviation:
              type: string
            logo:
              type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: MISSING_TOKEN
            message:
              type: string
              example: Authorization required
            hint:
              type: string
              example: 'Use Authorization: Bearer <your-api-key> or X-API-Key: <your-api-key>.'
          required:
          - code
          - message
      required:
      - success
      - error
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 25
        total:
          type: integer
          example: 180
        totalPages:
          type: integer
          example: 8
        pageCount:
          type: integer
          example: 8
          description: Present on some endpoints instead of totalPages.
        hasNextPage:
          type: boolean
          example: true
        hasPreviousPage:
          type: boolean
          example: false
    AvailabilityTransition:
      allOf:
      - $ref: '#/components/schemas/AvailabilityState'
      - type: object
        properties:
          sport:
            type: string
            example: football
          league:
            type: string
            example: nfl
          previousAvailability:
            type: string
          previousStatus:
            type: string
          changeType:
            type: string
            example: change
            enum:
            - new
            - change
            - cleared
    RateLimit:
      type: object
      properties:
        limit:
          type: integer
          example: 10000
          description: Calls included this month.
        remaining:
          type: integer
          example: 9876
          description: Calls remaining this month (approximate; updated asynchronously).
        reset:
          type: integer
          example: 1767225600000
          description: Quota reset time, Unix epoch milliseconds.
  responses:
    RateLimitExceeded:
      description: 'Too many requests: either the monthly quota is exhausted (code RATE_LIMIT_EXCEEDED; upgrade or enable overage) or the plan''s per-second rate was exceeded (code RATE_LIMIT_PER_SECOND; Free 1/s, Starter 5/s, Growth 10/s, Pro 20/s, Scale 100/s). Wait for `Retry-After` seconds.'
      headers:
        Retry-After:
          description: Seconds until you may retry.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'Missing, malformed, unknown or expired API key (codes: MISSING_TOKEN, USER_NOT_FOUND, TRIAL_EXPIRED).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected error. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key from the dashboard: `Authorization: Bearer <api key>`. Keys are opaque strings, not JWTs.'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative to the Authorization header (useful behind proxies that strip Authorization).
externalDocs:
  description: Guides, WebSocket and webhook docs
  url: https://www.realtimesportsapi.com/docs?utm_source=openapi
x-refined-from:
- original.json
- realtimesportsapi-com-openapi.json