lumify-ai Grade API

openapi: 3.2.0
info:
  title: Lumify Ai Grade 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 grade 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: grade
paths:
  /v1/grade/slip:
    post:
      tags:
      - grade
      summary: Grade settleable player-prop and game-market legs
      description: 'Grade settleable player-prop legs (over/under/push/in_progress/dnp/no_stat) on nfl/nba/ncaaf/ncaab/nhl/mlb/soccer, plus structured game markets (h2h/spreads/totals) on any sport GET /odds already settles. Structured event_id preferred; player_id is required on props and forbidden on game keys. Free-text player props are graded only when player and event resolve uniquely — ambiguous names stay unmapped with candidates. Call this endpoint or MCP grade_slip with an API key to grade from an app or agent. The public /grade sheet uses the same engine without a key (20 grades / IP / day). How-to: https://lumify.ai/docs/grade. Not live trading odds. Not wagering advice.'
      operationId: grade_slip_route_v1_grade_slip_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GradeSlipRequest'
        required: true
      responses:
        '200':
          description: 'Per-leg settlement (props: over / under / push / in_progress / dnp / no_stat; spreads and moneyline: won / lost / push / void / in_progress; totals: over / under / push / void / in_progress) plus a slip summary. Attribution is always Graded by Lumify.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GradeSlipResponse'
                additionalProperties: true
                type: object
                title: Response Grade Slip Route V1 Grade Slip Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyBearer: []
    servers:
    - url: https://lumify.ai
      description: Production
components:
  schemas:
    GradeSlipLeg:
      properties:
        input:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Input
          description: Parse echo of the leg (player, market_key, line, side, sport, team). Informational only — prefer market + resolve for the IDs and line that were actually graded.
        resolve:
          anyOf:
          - $ref: '#/components/schemas/GradeSlipResolve'
          - type: 'null'
        team_resolve:
          anyOf:
          - $ref: '#/components/schemas/GradeSlipTeamResolve'
          - type: 'null'
          description: Team mention on a free-text leg. A unique team_id scopes the player; ambiguous/not_found stays visible on the unmapped leg.
        event_resolve:
          anyOf:
          - $ref: '#/components/schemas/GradeSlipEventResolve'
          - type: 'null'
          description: Event bind on a free-text leg. A unique event_id is graded; ambiguous/not_found stays visible with candidates. Null on structured legs that already supplied event_id.
        market:
          anyOf:
          - $ref: '#/components/schemas/GradeSlipMarket'
          - type: 'null'
        current:
          anyOf:
          - type: number
          - type: 'null'
          title: Current
          description: 'Number compared to the line: prop box count, totals home+away, spreads home−away. Null on moneyline (read market.home_score / away_score) and when unmapped.'
        result:
          anyOf:
          - type: string
          - type: 'null'
          title: Result
          description: 'Props: in_progress | over | under | push | dnp | no_stat. Spreads and moneyline: won | lost | push | void | in_progress. Totals: over | under | push | void | in_progress. Null when unmapped.'
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      additionalProperties: true
      type: object
      title: GradeSlipLeg
    GradeSlipSummary:
      properties:
        graded:
          type: integer
          title: Graded
          default: 0
        pending:
          type: integer
          title: Pending
          default: 0
        unmapped:
          type: integer
          title: Unmapped
          default: 0
        hits:
          type: integer
          title: Hits
          default: 0
        misses:
          type: integer
          title: Misses
          default: 0
        pushes:
          type: integer
          title: Pushes
          default: 0
        voids:
          type: integer
          title: Voids
          description: Walkover, cancel, postpone, suspend, or retired legs. Not a miss and not unmapped.
          default: 0
      additionalProperties: true
      type: object
      title: GradeSlipSummary
    GradeSlipTeamResolve:
      properties:
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: resolved|ambiguous|not_found|error
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
        league:
          anyOf:
          - type: string
          - type: 'null'
          title: League
        abbreviation:
          anyOf:
          - type: string
          - type: 'null'
          title: Abbreviation
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
        match_reasons:
          items:
            type: string
          type: array
          title: Match Reasons
        sport_conflict:
          type: boolean
          title: Sport Conflict
          default: false
        candidates:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Candidates
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      additionalProperties: true
      type: object
      title: GradeSlipTeamResolve
    GradeSlipBranding:
      properties:
        attribution:
          type: string
          title: Attribution
          description: Always 'Graded by Lumify' on this surface.
        links:
          additionalProperties:
            type: string
          type: object
          title: Links
          default: {}
      additionalProperties: true
      type: object
      required:
      - attribution
      title: GradeSlipBranding
    GradeSlipLegInput:
      properties:
        event_id:
          type: integer
          title: Event Id
          description: Lumify event id.
        player_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Player Id
          description: Lumify player id from resolve_player or GET /v1/players. Required on player-prop markets. Forbidden on h2h, spreads, totals, and team_total.
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: Lumify team id from resolve_team or GET /v1/teams. Required on team_total. Forbidden on player-prop, h2h, spreads, and totals (those use side=home|away, not a team id).
        market_key:
          type: string
          title: Market Key
          description: 'Settleable player-prop slug (e.g. receiving_yards), game market h2h | spreads | totals, or team_total. Common aliases are accepted: player_reception_yds -> receiving_yards, moneyline/ml -> h2h, spread -> spreads, total/ou -> totals, team totals/tt -> team_total.'
        line:
          anyOf:
          - type: number
          - type: 'null'
          title: Line
          description: Submitted ticket line to grade against the official score. Required on player-prop, spreads, totals, and team_total legs — signed to the side on the ticket (e.g. side=home with a home -3.5 favorite is line=-3.5, not 3.5). Omit on h2h.
        side:
          type: string
          title: Side
          description: 'Player-prop, totals, and team_total: over | under (o | u also accepted). Spreads: home | away — matches the signed line above, not the favorite. Moneyline: home | away, or draw on soccer three-way.'
      additionalProperties: true
      type: object
      required:
      - event_id
      - market_key
      - side
      title: GradeSlipLegInput
    GradeSlipRequest:
      properties:
        legs:
          items:
            $ref: '#/components/schemas/GradeSlipLegInput'
          type: array
          title: Legs
          description: Structured legs (preferred). Cap 8.
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
          description: Free-text slip (e.g. "Chase over 74.5 receiving yards tonight"). Date words (today, tonight, yesterday, last night, last Wednesday, this Thursday, or an ISO date) narrow the event window. A roster-team mention (CIN, Niners) is resolved first — a unique team_id scopes the player; ambiguous/not_found stays on team_resolve. vs/at on a player prop is the opponent and narrows the event, not the player's team. Game phrases also include Yankees to win, Yankees over 4.5 runs (team_total), and Over 52.5 Syracuse vs Pittsburgh. A colliding nickname plus a date promotes only the unique in-window team; a football-sized line will not pick a baseball club, and vs plus that date keeps the unique matchup. A tennis moneyline with a full player name (Novak Djokovic ML) binds as a player, not a team; vs names the opponent player. Last-name-only tennis stays unmapped. A last-name-only player prop (Bergeron over 1.5 shots on goal last night) grades when a date is present and that surname is unique in scope — a named sport, team, or event narrows it (Johnson nhl last night); with no such clue, uniqueness is across every prop sport visible to the key. No date, or a surname shared by more than one player in that scope, still stays unmapped unless a date is present and exactly one of those candidates played in the window (optionally vs a named opponent). "anytime goal"/"anytime assist" implies soccer_goals/soccer_assists over 0.5 with no explicit number; "over a hit"/"over a homer" implies hits/home_runs over 1.0. Graded only when player and event resolve uniquely. Otherwise unmapped with candidates on resolve / team_resolve / event_resolve — free text never invents a grade.
        clues:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Clues
          description: Optional sport / league / event_id / team_id / team_text clues for free-text mode.
        options:
          $ref: '#/components/schemas/GradeSlipOptions'
      additionalProperties: true
      type: object
      title: GradeSlipRequest
    GradeSlipOptions:
      properties:
        include_branding:
          type: boolean
          title: Include Branding
          description: Attribution block is always present in this version.
          default: true
        max_legs:
          type: integer
          maximum: 8.0
          minimum: 1.0
          title: Max Legs
          description: v0 cap is 8 legs.
          default: 8
        auto_resolve:
          type: boolean
          title: Auto Resolve
          description: When free-text uniquely resolves a player and event, grade that leg. Ambiguous resolve never auto-picks a candidate.
          default: true
      additionalProperties: true
      type: object
      title: GradeSlipOptions
    GradeSlipEventResolve:
      properties:
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: resolved|ambiguous|not_found|error
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
        candidates:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Candidates
          description: Event candidates when status is ambiguous. Empty on a unique bind.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      additionalProperties: true
      type: object
      title: GradeSlipEventResolve
    GradeSlipResponse:
      properties:
        status:
          type: string
          title: Status
          description: graded | partial | pending | unmapped
        legs:
          items:
            $ref: '#/components/schemas/GradeSlipLeg'
          type: array
          title: Legs
        summary:
          $ref: '#/components/schemas/GradeSlipSummary'
        branding:
          $ref: '#/components/schemas/GradeSlipBranding'
        honesty:
          $ref: '#/components/schemas/GradeSlipHonesty'
        slip_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Slip Id
          description: Null in this version; share URLs are not persisted.
      additionalProperties: true
      type: object
      required:
      - status
      - legs
      - summary
      - branding
      - honesty
      title: GradeSlipResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GradeSlipHonesty:
      properties:
        notes:
          items:
            type: string
          type: array
          title: Notes
          default: []
      additionalProperties: true
      type: object
      title: GradeSlipHonesty
    GradeSlipMarket:
      properties:
        event_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Event Id
        market_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Market Key
        line:
          anyOf:
          - type: number
          - type: 'null'
          title: Line
        side:
          anyOf:
          - type: string
          - type: 'null'
          title: Side
        settleable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Settleable
        home_team:
          anyOf:
          - type: string
          - type: 'null'
          title: Home Team
          description: Null when the event never resolved to a row.
        away_team:
          anyOf:
          - type: string
          - type: 'null'
          title: Away Team
          description: Null when the event never resolved to a row.
        starts_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Starts At
          description: ISO-8601 UTC kickoff/first-pitch time. Null when the event never resolved to a row.
        home_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Home Score
          description: Official home (or player_1) numeric score. Null on tennis set-strings and when the event never resolved.
        away_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Away Score
          description: Official away (or player_2) numeric score. Null on tennis set-strings and when the event never resolved.
        team_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Id
          description: The team whose score was graded on a team_total leg. Null on other markets.
      additionalProperties: true
      type: object
      title: GradeSlipMarket
    GradeSlipResolve:
      properties:
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: resolved|ambiguous|not_found|error
        player_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Player Id
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        candidates:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Candidates
          description: Player candidates when status is ambiguous. Empty on a unique bind.
      additionalProperties: true
      type: object
      title: GradeSlipResolve
    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