lumify-ai Resolve API

openapi: 3.2.0
info:
  title: Lumify Ai Resolve 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 resolve 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: Resolve
paths:
  /v1/resolve/player:
    post:
      tags:
      - Resolve
      summary: Resolve a messy player name to a Lumify player id
      description: Resolve messy sports player names to a Lumify player_id using sport, team, or event clues. Prefer before grade_slip. Returns ambiguous instead of guessing.
      operationId: resolve_player_route_v1_resolve_player_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolvePlayerRequest'
        required: true
      responses:
        '200':
          description: resolved with player_id, or ambiguous / not_found. Never guesses when two catalog players remain plausible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvePlayerResponse'
                additionalProperties: true
                type: object
                title: Response Resolve Player Route V1 Resolve Player Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
  /v1/resolve/team:
    post:
      tags:
      - Resolve
      summary: Resolve a messy team string to a Lumify team id
      description: Resolve messy team names, abbreviations, metros, or aliases to a Lumify team_id using sport, league, event, or player clues. Returns ambiguous instead of guessing.
      operationId: resolve_team_route_v1_resolve_team_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveTeamRequest'
        required: true
      responses:
        '200':
          description: resolved with team_id, or ambiguous / not_found. Never guesses when two catalog teams remain plausible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveTeamResponse'
                additionalProperties: true
                type: object
                title: Response Resolve Team Route V1 Resolve Team Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
  /v1/resolve/event:
    post:
      tags:
      - Resolve
      summary: Resolve event identity from an id, player, or team clue
      description: Resolve event_id, or player_id/team_id + date window, to a Lumify event_id. Never guesses.
      operationId: resolve_event_route_v1_resolve_event_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveEventRequest'
        required: true
      responses:
        '200':
          description: resolved with event_id, or ambiguous / not_found. Never guesses when two catalog events remain plausible in the window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveEventResponse'
                additionalProperties: true
                type: object
                title: Response Resolve Event Route V1 Resolve Event Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
components:
  schemas:
    ResolvePlayerClues:
      properties:
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
          description: Sport slug, e.g. nfl or mlb.
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: Lumify team id.
        team_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Text
          description: Team abbreviation, slug, or name (e.g. CIN).
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
          description: Scope the match to this event's roster.
        position:
          anyOf:
          - type: string
          - type: 'null'
          title: Position
          description: Roster position abbreviation, e.g. WR or QB.
        vendor:
          anyOf:
          - type: string
          - type: 'null'
          title: Vendor
          description: Optional catalog source slug when vendor_player_key is set.
        vendor_player_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Vendor Player Key
          description: Exact catalog key from a connected source, when you already have one.
        as_of:
          anyOf:
          - type: string
          - type: 'null'
          title: As Of
          description: Reserved. Historical roster as-of is not applied in this version.
      additionalProperties: true
      type: object
      title: ResolvePlayerClues
    ResolvePlayerRequest:
      properties:
        query:
          type: string
          title: Query
          description: Messy player name or fragment, e.g. J. Chase.
          default: ''
        clues:
          $ref: '#/components/schemas/ResolvePlayerClues'
          description: Optional sport, team, event, position, or catalog-key clues.
        options:
          $ref: '#/components/schemas/ResolvePlayerOptions'
          description: Confidence floor, candidate cap, and match mode.
      additionalProperties: true
      type: object
      title: ResolvePlayerRequest
    ResolveEventCandidate:
      properties:
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
        league:
          anyOf:
          - type: string
          - type: 'null'
          title: League
        event_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Status
          description: scheduled | final | …
        starts_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Starts At
          description: ISO 8601 kickoff.
        home_team:
          anyOf:
          - type: string
          - type: 'null'
          title: Home Team
        away_team:
          anyOf:
          - type: string
          - type: 'null'
          title: Away Team
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
      additionalProperties: true
      type: object
      title: ResolveEventCandidate
    ResolveTeamClues:
      properties:
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
          description: Sport slug, e.g. nfl or mlb.
        league:
          anyOf:
          - type: string
          - type: 'null'
          title: League
          description: League slug, tighter than sport (e.g. mls, epl).
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
          description: Scope the match to this event's participants first.
        player_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Player Id
          description: Empty query uses this player's current team; otherwise a last-resort confirm.
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: Direct Lumify team id (also accepted as an all-digit query).
      additionalProperties: true
      type: object
      title: ResolveTeamClues
    ResolveEventResponse:
      properties:
        status:
          type: string
          title: Status
          description: resolved | ambiguous | not_found | error
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
          description: Set only when status is resolved.
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
        league:
          anyOf:
          - type: string
          - type: 'null'
          title: League
        event_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Status
          description: scheduled | final | …
        starts_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Starts At
          description: ISO 8601 kickoff.
        home_team:
          anyOf:
          - type: string
          - type: 'null'
          title: Home Team
        away_team:
          anyOf:
          - type: string
          - type: 'null'
          title: Away Team
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
        clues_used:
          items:
            type: string
          type: array
          title: Clues Used
        method:
          anyOf:
          - type: string
          - type: 'null'
          title: Method
          description: event_id | player_window | player_team_window | team_window | matchup_window.
        participant_conflict:
          type: boolean
          title: Participant Conflict
          description: True when event_id conflicts with an explicit player/team clue or date window.
          default: false
        candidates:
          items:
            $ref: '#/components/schemas/ResolveEventCandidate'
          type: array
          title: Candidates
          description: Plausible events when ambiguous.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      additionalProperties: true
      type: object
      required:
      - status
      title: ResolveEventResponse
    ResolveEventRequest:
      properties:
        clues:
          $ref: '#/components/schemas/ResolveEventClues'
          description: event_id, or player/team + date window.
        options:
          $ref: '#/components/schemas/ResolveEventOptions'
      additionalProperties: true
      type: object
      title: ResolveEventRequest
    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
    ResolveTeamOptions:
      properties:
        max_candidates:
          type: integer
          maximum: 25.0
          minimum: 1.0
          title: Max Candidates
          description: Maximum candidates to return when the match is ambiguous.
          default: 5
        min_confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Min Confidence
          description: Auto-resolve floor. Unique hits below this return ambiguous.
          default: 0.85
      additionalProperties: true
      type: object
      title: ResolveTeamOptions
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResolveTeamResponse:
      properties:
        status:
          type: string
          title: Status
          description: resolved | ambiguous | not_found | error
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: Set only when status is resolved.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Catalog display name.
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
          description: Resolved sport slug.
        league:
          anyOf:
          - type: string
          - type: 'null'
          title: League
          description: Resolved league slug.
        abbreviation:
          anyOf:
          - type: string
          - type: 'null'
          title: Abbreviation
          description: Catalog abbreviation.
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
          description: Auto-resolve confidence.
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
          description: Why the unique bind matched.
        clues_used:
          items:
            type: string
          type: array
          title: Clues Used
          description: Clue fields that were supplied.
        method:
          anyOf:
          - type: string
          - type: 'null'
          title: Method
          description: Kernel match method (abbreviation, nickname, alias, metro, …).
        sport_conflict:
          type: boolean
          title: Sport Conflict
          description: True when a ground-truth id/slug disagrees with an explicit sport or league clue.
          default: false
        candidates:
          items:
            $ref: '#/components/schemas/ResolveTeamCandidate'
          type: array
          title: Candidates
          description: Plausible teams when status is ambiguous.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable status note.
      additionalProperties: true
      type: object
      required:
      - status
      title: ResolveTeamResponse
    ResolveTeamRequest:
      properties:
        query:
          type: string
          title: Query
          description: 'Team string: nickname, abbreviation, slug, metro, or alias (e.g. Niners, CIN, NY Giants).'
          default: ''
        clues:
          $ref: '#/components/schemas/ResolveTeamClues'
          description: Optional sport, league, event, player, or team-id clues.
        options:
          $ref: '#/components/schemas/ResolveTeamOptions'
          description: Confidence floor and candidate cap.
      additionalProperties: true
      type: object
      title: ResolveTeamRequest
    ResolvePlayerResponse:
      properties:
        status:
          type: string
          title: Status
          description: resolved | ambiguous | not_found | error
        player_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Player Id
          description: Set only when status is resolved.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
          default: []
        clues_used:
          items:
            type: string
          type: array
          title: Clues Used
          default: []
        candidates:
          items:
            $ref: '#/components/schemas/ResolvePlayerCandidate'
          type: array
          title: Candidates
          default: []
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      additionalProperties: true
      type: object
      required:
      - status
      title: ResolvePlayerResponse
    ResolveEventClues:
      properties:
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
          description: Direct Lumify event id (ground truth).
        player_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Player Id
          description: Find this player's event (falls back to roster team schedule).
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: Find this team's event. Add opponent_team_id for a matchup.
        opponent_team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Opponent Team Id
          description: Narrows to a game against this team; requires team_id or player_id.
        start_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Date
          description: Inclusive UTC YYYY-MM-DD. Requires end_date.
        end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: End Date
          description: Inclusive UTC YYYY-MM-DD. Requires start_date.
      additionalProperties: true
      type: object
      title: ResolveEventClues
    ResolvePlayerOptions:
      properties:
        max_candidates:
          type: integer
          maximum: 25.0
          minimum: 1.0
          title: Max Candidates
          description: Maximum candidates to return when the match is ambiguous.
          default: 5
        min_confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Min Confidence
          description: Auto-resolve floor. Unique hits below this return ambiguous.
          default: 0.85
        mode:
          type: string
          title: Mode
          description: strict (exact / Jr / F.Last on a roster), permissive (unique last-token on event/team roster), or ingest (sport-wide fuzzy).
          default: strict
      additionalProperties: true
      type: object
      title: ResolvePlayerOptions
    ResolveEventOptions:
      properties:
        max_candidates:
          type: integer
          maximum: 25.0
          minimum: 1.0
          title: Max Candidates
          description: Candidate cap when ambiguous.
          default: 5
        min_confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Min Confidence
          description: Auto-resolve floor.
          default: 0.85
      additionalProperties: true
      type: object
      title: ResolveEventOptions
    ResolveTeamCandidate:
      properties:
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: Lumify team id.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Catalog display name.
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
          description: Sport slug.
        league:
          anyOf:
          - type: string
          - type: 'null'
          title: League
          description: League slug.
        abbreviation:
          anyOf:
          - type: string
          - type: 'null'
          title: Abbreviation
          description: Catalog abbreviation.
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
          description: Per-candidate confidence.
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
          description: Why this candidate matched.
      additionalProperties: true
      type: object
      title: ResolveTeamCandidate
    ResolvePlayerCandidate:
      properties:
        player_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Player Id
          description: Lumify player id.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Catalog display name.
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
          default: []
      additionalProperties: true
      type: object
      title: ResolvePlayerCandidate
  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