lumify-ai Players API

openapi: 3.2.0
info:
  title: Lumify Ai Players API
  version: 1.0.0
  contact:
    name: Lumify Support
    url: https://lumify.ai/contact-us
    email: support@lumify.ai
  license:
    name: Terms of Service
    url: https://lumify.ai/terms-of-service
  description: 'Operations tagged players across 2 of this provider''s published API definitions: openapi.json, lumify-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://lumify.ai
  description: Production
tags:
- name: Players
  description: Player profiles and participation history.
paths:
  /v1/players:
    get:
      tags:
      - Players
      summary: List players
      operationId: list_players_v1_players_get
      parameters:
      - name: sport
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Sport slug, e.g. 'tennis' or 'mlb'
          title: Sport
        description: Sport slug, e.g. 'tennis' or 'mlb'
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Name search (partial match)
          title: Q
        description: Name search (partial match)
      - name: country
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 3166-1 alpha-3 country code, e.g. 'USA'
          title: Country
        description: ISO 3166-1 alpha-3 country code, e.g. 'USA'
      - name: active
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Filter by active status
          title: Active
        description: Filter by active status
      - name: ranked
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: If true, only tennis players with an ATP/WTA singles ranking (rankings.singles).
          title: Ranked
        description: If true, only tennis players with an ATP/WTA singles ranking (rankings.singles).
      - name: after_id
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: 'Cursor: last player id from previous page'
          default: 0
          title: After Id
        description: 'Cursor: last player id from previous page'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayersListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
  /v1/players/{player_id}:
    get:
      tags:
      - Players
      summary: Get a player
      operationId: get_player_v1_players__player_id__get
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          title: Player Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
  /v1/players/{player_id}/events:
    get:
      tags:
      - Players
      summary: List a player's events
      operationId: get_player_events_v1_players__player_id__events_get
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
          title: Player Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Event status filter
          title: Status
        description: Event status filter
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start date YYYY-MM-DD
          title: From
        description: Start date YYYY-MM-DD
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End date YYYY-MM-DD
          title: To
        description: End date YYYY-MM-DD
      - name: after_id
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: 'Cursor: last event id from previous page'
          default: 0
          title: After Id
        description: 'Cursor: last event id from previous page'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerEventsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
components:
  schemas:
    PlayerRankings:
      properties:
        singles:
          anyOf:
          - type: integer
          - type: 'null'
          title: Singles
          description: ATP/WTA singles ranking. Tennis only.
        points:
          anyOf:
          - type: integer
          - type: 'null'
          title: Points
          description: ATP/WTA ranking points. Tennis only.
      additionalProperties: true
      type: object
      title: PlayerRankings
    PlayersListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Player'
          type: array
          title: Data
          default: []
        has_more:
          type: boolean
          title: Has More
          default: false
        next_after_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next After Id
      additionalProperties: true
      type: object
      title: PlayersListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Player:
      properties:
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
          description: Lumify player ID.
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
          description: URL-safe unique slug.
        full_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Full Name
          description: Display name.
        first_name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
          description: Sport slug, e.g. mlb, tennis, nfl.
        country_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Code
          description: ISO 3166-1 alpha-3 country code.
        birthdate:
          anyOf:
          - type: string
          - type: 'null'
          title: Birthdate
          description: YYYY-MM-DD date of birth.
        position:
          anyOf:
          - type: string
          - type: 'null'
          title: Position
          description: Roster position abbreviation when the sport has one (e.g. C, P, SS for MLB; QB, WR for NFL). Null for tennis and when not yet ingested.
        handedness:
          anyOf:
          - type: string
          - type: 'null'
          title: Handedness
          description: left | right | switch. Meaning is sport-specific (bats for MLB, shoots for NHL, playing hand for tennis). Null when unknown.
        height_cm:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height Cm
          description: Height in centimetres. Null when not ingested.
        weight_kg:
          anyOf:
          - type: number
          - type: 'null'
          title: Weight Kg
          description: Weight in kilograms. Null when not ingested.
        rankings:
          anyOf:
          - $ref: '#/components/schemas/PlayerRankings'
          - type: 'null'
          description: 'Sport ranking block. Tennis: {singles, points} from ATP/WTA standings. Null for every other sport. Tennis /stats also exposes ranking / ranking_points on the tennis player block.'
        current_team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Team Id
          description: Lumify team ID when the player is on a club roster. Null for tennis.
        current_team_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Team Name
          description: Current team display name. Null for tennis.
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
          description: False when deactivated or retired.
        retired_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Retired At
          description: YYYY-MM-DD retirement date when known.
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
          description: Lumify media URL for the player headshot (https://lumify.ai/media/players/{sport}/{id}.{ext}). Null until the sport's headshot/enrichment job. Never a vendor CDN.
      additionalProperties: true
      type: object
      title: Player
      description: 'Directory identity for one player. Shared keys on every sport; null means

        unknown, not ''wrong sport''. Sport-named metrics do not live here —

        tennis ranking is ``rankings`` (null on every other sport). Tennis

        ``/stats`` also exposes ``ranking`` / ``ranking_points`` on the tennis

        player block.'
    PlayerEventsResponse:
      properties:
        player_id:
          type: integer
          title: Player Id
        data:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Data
          default: []
        has_more:
          type: boolean
          title: Has More
          default: false
        next_after_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next After Id
      additionalProperties: true
      type: object
      required:
      - player_id
      title: PlayerEventsResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: lmfy-key
      description: 'Lumify API key passed as `Authorization: Bearer lmfy-...`.'
x-refined-from:
- openapi.json
- lumify-ai-openapi.json