# PlayCaller Data API — OpenAPI 3.0.3
# Auto-generated by scripts/generate-openapi.js
# Generated: 2026-07-03T03:55:40.739Z
# Route count: 60 routes in daas-router.js → 54 paths in spec

openapi: 3.0.3
info:
  title: PlayCaller Data API
  version: 1.4.0
  description: |
      The PlayCaller Data API delivers real-time and historical sports intelligence for fantasy, DFS, and AI developers.
      
      49 REST endpoints across NFL, MLB, NBA, NHL, College Football, Soccer, Tennis, and Golf — plus TypeScript SDK, Python SDK, and an MCP server for AI workflow integration.
      
      ## Key capabilities
      - **8 sports** with live data pipelines: NFL, MLB, NBA, NHL, CFB, Soccer (EPL/MLS/La Liga/Bundesliga/Serie A/UCL), Tennis (ATP/WTA), Golf (PGA/LPGA)
      - **13,606 canonical player identities** normalized across ESPN, Sleeper, Yahoo, NFL.com, and BallDontLie
      - **AUC-validated ML models**: NFL confidence (AUC 0.697), NFL heat (AUC 0.623), MLB pitcher form (AUC 0.671), NBA confidence (AUC 0.855)
      - **Alpha metrics**: consistency score, momentum delta, opportunity ceiling per player
      - **Semantic similarity**: pgvector cosine search — find players with matching production profiles
      - **Real-time delivery**: SSE stream (Pro Insights+), HMAC-signed webhooks (Syndicate Alpha)
      - **AI-first**: MCP server at `/mcp`, ChatGPT plugin manifest at `/.well-known/ai-plugin.json`
      - **SDKs**: `npm install @playcaller/sdk` (TypeScript), `pip install playcaller-sdk` (Python)
      
      ## Authentication
      All data endpoints require an `X-PlayCaller-Key` header. Keys are issued at [playcallerapp.com/developer](https://playcallerapp.com/developer). Sandbox keys work immediately — no credit card required.
      
      Key format by tier: `pc_sbx_...` (Sandbox), `pc_bld_...` (Build), `pc_pri_...` (Pro Insights), `pc_syn_...` (Syndicate Alpha). Legacy keys issued before the V2 tier restructure may still carry `pc_hob_...` (Hobbyist) or `pc_pro_...` (Pro) prefixes.
      
      ## Base URLs
      - Data endpoints (v1 prefix): `https://playcallerapp.com/v1`
      - Intelligence endpoints (no prefix): `https://playcallerapp.com/intelligence`
      - Analytics endpoint (no prefix): `https://playcallerapp.com/analytics`
      - MCP server: `https://playcallerapp.com/mcp`
      - Account endpoints: `https://playcallerapp.com/daas`
      
      ## Tiers
      
      | Plan | Price | Daily calls | Req/min | Endpoints |
      |------|-------|------------|---------|-----------|
      | (tier data unavailable — set DATABASE_URL and regenerate) | | | | |
      
      ## Rate Limiting
      - `X-RateLimit-Limit`: Requests allowed per minute
      - `X-RateLimit-Remaining`: Remaining this window
      - `X-RateLimit-Reset`: Unix timestamp when window resets
      - `429` responses include a `Retry-After` header in seconds
  contact:
    name: PlayCaller Support
    url: "https://playcallerapp.com/developer/docs"
  termsOfService: "https://playcallerapp.com/developer/terms"
servers:
  - url: "https://playcallerapp.com"
    description: Production
tags:
  - name: Intelligence
    description: Beat reporter signals, injury feeds, and historical analytics. These routes have no /v1 prefix.
  - name: NFL
    description: NFL players, games, standings, and team rosters (2024 season backfilled, 2026 schedule live)
  - name: MLB
    description: MLB player data, game states, standings, and fantasy scoring
  - name: NBA
    description: NBA game scores, standings, teams, player profiles, and game logs
  - name: CFB
    description: College football scoreboard, standings, and rankings (Pro only)
  - name: Soccer
    description: Soccer match scores and league tables (EPL + MLS)
  - name: Multi
    description: Multi-sport discovery, cross-sport player search, and public stats endpoints
  - name: Account
    description: API key management, quota monitoring, and trial activation
  - name: MCP
    description: Model Context Protocol server — AI workflow integration for Cursor, Claude Desktop, and enterprise AI agents
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-PlayCaller-Key
      description: Your PlayCaller API key. Obtain one free at playcallerapp.com/developer.
  schemas:
    ErrorResponse:
      type: object
      required:
        - error_code
        - message
        - documentation_url
      properties:
        error_code:
          type: string
          example: RATE_LIMIT_EXCEEDED
        message:
          type: string
          example: Rate limit exceeded. Try again in 42 seconds.
        documentation_url:
          type: string
          format: uri
          example: "https://playcallerapp.com/developer/docs"
        upgrade_url:
          type: string
          format: uri
          nullable: true
          example: "https://playcallerapp.com/developer/checkout?tier=pro"
    ResponseMeta:
      type: object
      properties:
        sport:
          type: string
          example: nfl
        league:
          type: string
          example: nfl
          description: "Present on multi-sport (ESPN-backed) endpoints; mirrors sport unless a sport has sub-leagues (e.g. soccer: epl/mls)."
        tier:
          type: string
          example: pro
        calls_remaining_this_month:
          type: integer
          example: 9843
        documentation_url:
          type: string
          format: uri
          example: "https://playcallerapp.com/developer/docs"
    BeatReporterSignal:
      type: object
      required:
        - id
        - player_name
        - team
        - signal_type
        - severity
        - title
        - summary
        - source
      properties:
        id:
          type: integer
          example: 38
        player_name:
          type: string
          example: Zavion Thomas
        team:
          type: string
          example: SF
          description: Often an empty string — team is not always resolved at scrape time
        signal_type:
          type: string
          enum:
            - injury_update
            - depth_chart_change
            - return_from_injury
            - role_reduction
            - role_expansion
            - practice_report
          example: injury_update
        severity:
          type: string
          enum:
            - high
            - medium
            - low
          example: high
        title:
          type: string
          example: McCaffrey questionable with hamstring — listed DNP
        summary:
          type: string
          example: Christian McCaffrey did not practice Wednesday with a hamstring injury. He is listed DNP and is considered questionable for Sunday.
        source:
          type: string
          example: ESPN NFL Injury Report
        source_url:
          type: string
          format: uri
          nullable: true
          example: "https://www.espn.com/nfl/injuries"
        published_at:
          type: string
          format: date-time
          nullable: true
          description: /intelligence/news only — see reported_at for /intelligence/injuries
          example: "2026-06-24T19:12:10.637Z"
        reported_at:
          type: string
          format: date-time
          nullable: true
          description: /intelligence/injuries only — see published_at for /intelligence/news
          example: "2026-06-24T19:12:10.637Z"
    PlayerIdentity:
      type: object
      required:
        - playcaller_id
        - full_name
        - position
        - team
        - sport_key
      properties:
        playcaller_id:
          type: string
          description: Canonical PlayCaller player ID — stable across all platforms
          example: pc_nfl_001234
        full_name:
          type: string
          example: Christian McCaffrey
        position:
          type: string
          example: RB
        team:
          type: string
          example: SF
        sport_key:
          type: string
          enum:
            - nfl
            - mlb
            - nba
          example: nfl
        status:
          type: string
          enum:
            - active
            - injured
            - inactive
          example: active
        platform_ids:
          type: object
          description: Platform-specific IDs for this player. Keys are platform names; values are IDs used by that platform.
          additionalProperties:
            type: string
          example:
            espn: "3054211"
            sleeper: "4034"
            yahoo: "28849"
            nfl.com: mccaffrey-christian
    HistoricalGameRecord:
      type: object
      properties:
        id:
          type: integer
          example: 9121
        season:
          type: integer
          example: 2025
        week:
          type: integer
          nullable: true
          example: 18
          description: NFL/NBA only — null for MLB (daily games, no week concept)
        game_date:
          type: string
          format: date-time
          nullable: true
          example: null
          description: Real date for MLB (daily_player_stats.stat_date); always null for NFL, which has no per-game date column
        sport_key:
          type: string
          example: nfl
        player_name:
          type: string
          example: Josh Allen
        team:
          type: string
          example: BUF
        position:
          type: string
          example: QB
        opponent:
          type: string
          nullable: true
          example: MIA
        fantasy_points:
          type: string
          example: "35.30"
          description: Numeric value returned as a string
        passing_yards:
          type: integer
          nullable: true
        passing_tds:
          type: integer
          nullable: true
        rushing_yards:
          type: integer
          nullable: true
          example: 131
        rushing_tds:
          type: integer
          nullable: true
          example: 2
        receiving_yards:
          type: integer
          nullable: true
          example: 22
        receiving_tds:
          type: integer
          nullable: true
          example: 1
        receptions:
          type: integer
          nullable: true
          example: 2
        snap_pct:
          type: integer
          nullable: true
          example: 47
        target_share:
          type: number
          nullable: true
        air_yards:
          type: number
          nullable: true
        batting_h:
          type: integer
          nullable: true
          description: MLB only
        batting_r:
          type: integer
          nullable: true
        batting_hr:
          type: integer
          nullable: true
        batting_rbi:
          type: integer
          nullable: true
        batting_sb:
          type: integer
          nullable: true
        batting_bb:
          type: integer
          nullable: true
        batting_ab:
          type: integer
          nullable: true
        pitching_ip:
          type: number
          nullable: true
        pitching_w:
          type: integer
          nullable: true
        pitching_k:
          type: integer
          nullable: true
        pitching_sv:
          type: integer
          nullable: true
        pitching_hld:
          type: integer
          nullable: true
        pitching_er:
          type: integer
          nullable: true
    HistoricalTrend:
      type: object
      properties:
        player_name:
          type: string
          example: Rhamondre Stevenson
        team:
          type: string
          example: NE
        position:
          type: string
          example: RB
        sport:
          type: string
          example: nfl
        games_in_sample:
          type: integer
          example: 1
        avg_fantasy_points:
          type: number
          example: 35.3
        recent_game:
          $ref: "#/components/schemas/HistoricalGameRecord"
        all_games:
          type: array
          items:
            $ref: "#/components/schemas/HistoricalGameRecord"
    MLBPlayer:
      type: object
      required:
        - id
        - full_name
        - position
        - team
        - status
      properties:
        id:
          type: string
          description: PlayCaller MLB player ID
          example: pc_mlb_001234
        full_name:
          type: string
          example: Shohei Ohtani
        first_name:
          type: string
          example: Shohei
        last_name:
          type: string
          example: Ohtani
        position:
          type: string
          enum:
            - SP
            - RP
            - C
            - 1B
            - 2B
            - 3B
            - SS
            - OF
            - DH
          example: DH
        team:
          type: string
          example: LAD
        status:
          type: string
          enum:
            - active
            - injured
            - inactive
          example: active
    MLBPlayerStats:
      type: object
      properties:
        rank:
          type: integer
          nullable: true
          example: 1
          description: Leaders endpoint only
        id:
          type: string
          nullable: true
          example: pc_mlb_672640
          description: Leaders endpoint only
        player_name:
          type: string
          nullable: true
          example: Otto Lopez
          description: Leaders endpoint only
        team:
          type: string
          example: Miami Marlins
        position:
          type: string
          example: SS
        stat_date:
          type: string
          format: date-time
          example: "2026-06-24T07:00:00.000Z"
        game_pk:
          type: string
          nullable: true
          example: "822800"
          description: Player-stats endpoint only
        fantasy_points:
          type: string
          example: "8.50"
          description: Numeric value returned as a string
        is_final:
          type: boolean
          example: true
        is_starter:
          type: boolean
          nullable: true
          description: Player-stats endpoint only
        last_updated:
          type: string
          format: date-time
          nullable: true
          description: Player-stats endpoint only
        batting:
          type: object
          properties:
            h:
              type: integer
              description: Hits
              example: 2
            r:
              type: integer
              description: Runs Scored
              example: 2
            hr:
              type: integer
              description: Home Runs
              example: 1
            rbi:
              type: integer
              description: RBI
              example: 3
            sb:
              type: integer
              description: Stolen Bases
              example: 1
            bb:
              type: integer
              description: Walks
              example: 1
            ab:
              type: integer
              nullable: true
              description: At Bats — player-stats endpoint only
            pa:
              type: integer
              nullable: true
              description: Plate Appearances — player-stats endpoint only
        pitching:
          type: object
          nullable: true
          properties:
            ip:
              type: string
              description: Innings Pitched, returned as a string (e.g. "6.2")
              example: "6.2"
            w:
              type: integer
              description: Wins
              example: 0
            k:
              type: integer
              description: Strikeouts
              example: 9
            sv:
              type: integer
              description: Saves
              example: 0
            hld:
              type: integer
              description: Holds
              example: 0
            er:
              type: integer
              description: Earned Runs
              example: 1
    MLBGame:
      type: object
      properties:
        game_pk:
          type: string
          example: "745302"
          description: MLB Stats API game ID — returned as a string, not numeric
        game_date:
          type: string
          format: date-time
          example: "2026-05-01T00:00:00.000Z"
        game_time:
          type: string
          format: date-time
          nullable: true
          example: "2026-05-01T22:10:00.000Z"
        state:
          type: string
          enum:
            - pre_game
            - scheduled
            - in_progress
            - final
            - completed
            - postponed
          example: completed
          description: Real values from mlb_game_states — not the previously-documented live/final/preview enum
        home_team:
          type: object
          properties:
            id:
              type: integer
              example: 146
            name:
              type: string
              example: Miami Marlins
            score:
              type: integer
              nullable: true
              example: 4
        away_team:
          type: object
          properties:
            id:
              type: integer
              example: 140
            name:
              type: string
              example: Texas Rangers
            score:
              type: integer
              nullable: true
              example: 2
        inning:
          type: integer
          nullable: true
          example: 9
        inning_state:
          type: string
          nullable: true
          example: Top
        lineup_posted:
          type: boolean
        is_final:
          type: boolean
          example: true
        status_code:
          type: string
          example: F
        last_polled:
          type: string
          format: date-time
          example: "2026-05-01T22:14:05Z"
    ESPNGame:
      type: object
      description: Game state from ESPN feed (NBA, CFB, Soccer)
      properties:
        event_id:
          type: string
          example: "740975"
        league:
          type: string
          nullable: true
          example: epl
          description: Soccer only (epl/mls) — distinguishes league within the sport
        game_date:
          type: string
          format: date-time
          example: "2026-05-24T07:00:00.000Z"
        game_time:
          type: string
          format: date-time
          example: "2026-05-24T15:00:00.000Z"
        state:
          type: string
          enum:
            - scheduled
            - in_progress
            - final
          example: final
          description: Real values from espn_game_states — not the previously-documented pre/in/post
        home_team:
          type: object
          properties:
            id:
              type: string
              example: "18"
            name:
              type: string
              example: Los Angeles Lakers
            abbr:
              type: string
              example: LAL
            logo:
              type: string
              format: uri
              example: "https://a.espncdn.com/i/teamlogos/nba/500/lal.png"
            score:
              type: integer
              nullable: true
              example: 112
        away_team:
          type: object
          properties:
            id:
              type: string
              example: "2"
            name:
              type: string
              example: Boston Celtics
            abbr:
              type: string
              example: BOS
            logo:
              type: string
              format: uri
              example: "https://a.espncdn.com/i/teamlogos/nba/500/bos.png"
            score:
              type: integer
              nullable: true
              example: 108
        period:
          type: integer
          nullable: true
          example: 4
        period_label:
          type: string
          nullable: true
          example: Q4
        clock:
          type: string
          nullable: true
          example: "2:14"
        venue:
          type: string
          nullable: true
          example: Crypto.com Arena
        broadcast:
          type: string
          nullable: true
          example: TNT
        is_final:
          type: boolean
          example: true
        last_polled:
          type: string
          format: date-time
          example: "2026-05-01T02:14:05Z"
    ESPNStanding:
      type: object
      properties:
        rank:
          type: integer
          example: 1
        league:
          type: string
          nullable: true
          example: epl
          description: Soccer only (epl/mls)
        ties:
          type: integer
          nullable: true
          description: Soccer only — NBA/CFB have no tie record
        team_id:
          type: string
          example: "2"
        team_name:
          type: string
          example: Boston Celtics
        team_abbr:
          type: string
          example: BOS
        team_logo:
          type: string
          format: uri
          nullable: true
        conference:
          type: string
          nullable: true
          example: East
        division:
          type: string
          nullable: true
          example: Atlantic
        wins:
          type: integer
          example: 64
        losses:
          type: integer
          example: 18
        win_pct:
          type: number
          format: float
          example: 0.78
        games_back:
          type: string
          nullable: true
          example: "-"
        streak:
          type: string
          nullable: true
          example: W3
        home_record:
          type: string
          nullable: true
          example: 36-5
        away_record:
          type: string
          nullable: true
          example: 28-13
        conf_record:
          type: string
          nullable: true
          example: 42-14
        points_for:
          type: number
          format: float
          nullable: true
          example: 120.4
        points_against:
          type: number
          format: float
          nullable: true
          example: 109.8
        last_updated:
          type: string
          format: date-time
          nullable: true
    CFBRanking:
      type: object
      properties:
        rank:
          type: integer
          example: 1
        team_id:
          type: string
          example: cfb_alabama
        team_name:
          type: string
          example: Alabama
        team_abbr:
          type: string
          example: ALA
        record:
          type: string
          example: 12-0
        points:
          type: integer
          nullable: true
          example: 1550
        first_place_votes:
          type: integer
          nullable: true
          example: 42
        prev_rank:
          type: integer
          nullable: true
          example: 1
        week:
          type: integer
          example: 15
    UsageStats:
      type: object
      properties:
        success:
          type: boolean
        key_prefix:
          type: string
          example: pcdk_test_9b...
        tier:
          type: string
          enum:
            - sandbox
            - hobbyist
            - build
            - pro
            - pro_insights
            - enterprise
            - syndicate_alpha
          example: pro
        tier_limits:
          type: object
          description: Reference limits for every legacy tier (V2 tiers are not monthly-metered, so they are not listed here — see GET /v1/sports or the pricing table for sandbox/build/pro_insights/syndicate_alpha caps)
          additionalProperties:
            type: object
            properties:
              requests_per_minute:
                type: integer
              daily_calls:
                type: integer
                nullable: true
              monthly_calls:
                type: integer
                nullable: true
        is_trial:
          type: boolean
          example: false
        trial_starts_at:
          type: string
          format: date-time
          nullable: true
        trial_ends_at:
          type: string
          format: date-time
          nullable: true
        trial_days_remaining:
          type: integer
          nullable: true
          description: Days left in trial (null if not in trial)
        requests_today:
          type: integer
          example: 0
        daily_limit:
          type: integer
          nullable: true
          example: 1000
        daily_remaining:
          type: integer
          nullable: true
          example: 1000
        calls_this_period:
          type: integer
          example: 0
        calls_this_month:
          type: integer
          example: 157
        calls_limit_month:
          type: integer
          example: 10000
        calls_remaining:
          type: integer
          example: 9843
        rate_limit_per_min:
          type: integer
          example: 60
        rate_limit_remaining:
          type: integer
          example: 59
        reset_at:
          type: string
          format: date-time
          nullable: true
          description: When monthly quota resets (legacy tiers only — null for V2 tiers, which are not monthly-metered)
          example: "2026-06-01T00:00:00Z"
        upgrade_url:
          type: string
          format: uri
          nullable: true
        endpoint_breakdown:
          type: array
          description: Per-endpoint call counts for the trailing 30 days — an array of rows, not a map (returned empty for RapidAPI-proxied keys, which have no DB usage row)
          items:
            type: object
            properties:
              endpoint:
                type: string
              calls:
                type: integer
              avg_ms:
                type: integer
              last_call:
                type: string
                format: date-time
    MCPTool:
      type: object
      required:
        - name
        - description
        - inputSchema
      properties:
        name:
          type: string
          example: get_injury_signals
        description:
          type: string
          example: Returns active beat reporter injury signals filtered by sport and severity.
        inputSchema:
          type: object
          description: JSON Schema for tool arguments
          properties:
            type:
              type: string
              example: object
            properties:
              type: object
              additionalProperties: true
            required:
              type: array
              items:
                type: string
    PublicStats:
      type: object
      properties:
        active_users:
          type: integer
          description: Registered users with at least one login this month
          example: 4182
        active_signals:
          type: integer
          description: Beat reporter signals currently active across all sports
          example: 625
        players_tracked:
          type: integer
          description: Total canonical player identities in the database
          example: 13606
        sports_covered:
          type: integer
          description: Number of sports with live data pipelines
          example: 5
        platforms:
          type: integer
          description: External platforms with cross-platform player ID mappings
          example: 6
paths:
  /intelligence/news:
    get:
      tags:
        - Intelligence
      summary: Live multi-sport player signals
      description: |
          Returns real-time player signals scraped every 2 hours from ESPN NFL, MLB, and NBA injury reports and beat reporter feeds. Signals surface before they appear on mainstream aggregators.
          
          Includes injuries, depth chart changes, role shifts, practice participation, and return-to-practice designations across all three sports. Signal severity is calculated based on fantasy impact: a DNP for a workhorse RB is `high`; a minor hamstring note for a backup is `low`.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getIntelligenceNews
      parameters:
        - name: severity
          in: query
          description: Filter by fantasy impact severity
          schema:
            type: string
            enum:
              - high
              - medium
              - low
          example: high
        - name: sport
          in: query
          description: Filter by sport (defaults to all)
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
              - all
          example: nfl
        - name: team
          in: query
          description: Filter by 2-3 letter team abbreviation
          schema:
            type: string
            maxLength: 3
          example: SF
        - name: position
          in: query
          description: "Filter by position (NFL: QB/RB/WR/TE/K; MLB: SP/OF/etc; NBA: PG/SG/etc)"
          schema:
            type: string
          example: WR
        - name: signal_type
          in: query
          description: Filter by signal category
          schema:
            type: string
            enum:
              - injury
              - depth_chart
              - role_shift
              - practice_report
              - return_to_practice
          example: injury
        - name: limit
          in: query
          description: Max results (default 25, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          example: 25
      responses:
        200:
          description: Active player signals ordered by severity then recency
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/BeatReporterSignal"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /intelligence/injuries:
    get:
      tags:
        - Intelligence
      summary: Active injury feed (multi-sport)
      description: |
          Filtered view of the signal feed returning only active injury designations across NFL, MLB, and NBA. Equivalent to `GET /intelligence/news?signal_type=injury` with convenience defaults tuned for DFS stack-building and lineup decisions.
          
          625+ active signals are re-scraped every 2 hours. High-severity signals are available before mainstream platforms aggregate them.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getIntelligenceInjuries
      parameters:
        - name: severity
          in: query
          description: Minimum severity level
          schema:
            type: string
            enum:
              - high
              - medium
              - low
          example: high
        - name: sport
          in: query
          description: Sport filter (defaults to nfl)
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
              - all
          example: nfl
        - name: team
          in: query
          description: 2-3 letter team abbreviation
          schema:
            type: string
            maxLength: 3
          example: KC
        - name: player
          in: query
          description: Partial player name search (case-insensitive)
          schema:
            type: string
          example: Mahomes
        - name: limit
          in: query
          description: Max results (default 50, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          example: 50
      responses:
        200:
          description: Active injury signals ordered by severity then recency
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/BeatReporterSignal"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /analytics/trends:
    get:
      tags:
        - Intelligence
      summary: Historical performance trends (Pro)
      description: |
          Game-by-game performance logs for NFL (2024 full season, 4,624 records) and MLB players. Each row represents one game: full stat line plus calculated fantasy points under PPR, half-PPR, or standard scoring.
          
          Use this endpoint to calculate targets-per-route, air yards share, snap consistency, and multi-week usage trends — the signals that separate week-winning waiver adds from noise.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getAnalyticsTrends
      parameters:
        - name: sport
          in: query
          description: "Sport to query (default: nfl)"
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - all
          example: nfl
        - name: player_name
          in: query
          description: Partial player name (case-insensitive)
          schema:
            type: string
          example: McCaffrey
        - name: team
          in: query
          description: 2-3 letter team abbreviation
          schema:
            type: string
            maxLength: 3
          example: SF
        - name: position
          in: query
          description: Position (QB/RB/WR/TE for NFL; SP/OF/etc for MLB)
          schema:
            type: string
          example: WR
        - name: season
          in: query
          description: "Season year (NFL: 2024; MLB: 2024)"
          schema:
            type: integer
          example: 2024
        - name: week
          in: query
          description: NFL week number (1–18)
          schema:
            type: integer
            minimum: 1
            maximum: 18
          example: 8
        - name: limit
          in: query
          description: Max records (default 50, max 500)
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
          example: 50
      responses:
        200:
          description: Players grouped with their recent game and full game log in the requested window
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  sport:
                    type: string
                    example: nfl
                  seasons:
                    type: array
                    items:
                      type: integer
                    example:
                      - 2025
                  total_records:
                    type: integer
                    description: Total game rows considered before grouping by player
                  trends:
                    type: array
                    items:
                      $ref: "#/components/schemas/HistoricalTrend"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/mlb/players:
    get:
      tags:
        - MLB
      summary: List active MLB players
      description: |
          Returns all active MLB players (966 total). Positions, teams, and statuses are normalized from MLB Stats API and reconciled against ESPN for accuracy.
          
          Filter by position and team to build DFS pools or lineup constraints without doing the normalization yourself.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listMLBPlayers
      parameters:
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - SP
              - RP
              - C
              - 1B
              - 2B
              - 3B
              - SS
              - OF
              - DH
          example: SP
        - name: team
          in: query
          description: 3-letter MLB team abbreviation
          schema:
            type: string
          example: NYY
        - name: status
          in: query
          description: Filter by player status
          schema:
            type: string
            enum:
              - active
              - injured
              - inactive
          example: active
        - name: search
          in: query
          description: Partial name search (case-insensitive)
          schema:
            type: string
          example: Ohtani
        - name: limit
          in: query
          description: Max results (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        200:
          description: Paginated list of MLB players
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  total:
                    type: integer
                  count:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MLBPlayer"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/mlb/players/{id}":
    get:
      tags:
        - MLB
      summary: Get MLB player by ID
      description: |
          Returns the full profile for a single MLB player by PlayCaller ID. Use `/v1/mlb/players?search=` to find IDs by name.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getMLBPlayer
      parameters:
        - name: id
          in: path
          required: true
          description: "PlayCaller MLB player ID (format: pc_mlb_XXXXXX)"
          schema:
            type: string
          example: pc_mlb_001234
      responses:
        200:
          description: MLB player profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: "#/components/schemas/MLBPlayer"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Player not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: PLAYER_NOT_FOUND
                message: No player found with ID pc_mlb_999999.
                documentation_url: "https://playcallerapp.com/developer/docs#mlb"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/mlb/players/{id}/stats":
    get:
      tags:
        - MLB
      summary: Game-by-game stats for an MLB player
      description: |
          Returns daily batting and pitching stat lines with pre-calculated fantasy points. Useful for tracking recent form, streaks, and park-factor-adjusted production.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getMLBPlayerStats
      parameters:
        - name: id
          in: path
          required: true
          description: PlayCaller MLB player ID
          schema:
            type: string
          example: pc_mlb_001234
        - name: date
          in: query
          description: Filter to a specific game date (YYYY-MM-DD)
          schema:
            type: string
            format: date
          example: 2026-05-01
        - name: limit
          in: query
          description: Max game logs (default 30, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 30
          example: 30
      responses:
        200:
          description: Player game-by-game stat log
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  player:
                    type: object
                    properties:
                      id:
                        type: string
                      full_name:
                        type: string
                      position:
                        type: string
                      team:
                        type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MLBPlayerStats"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Player not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/mlb/teams:
    get:
      tags:
        - MLB
      summary: All 30 MLB teams
      description: |
          Returns metadata for all 30 MLB teams including roster depth. Abbreviations are normalized (e.g. NYY, BOS, LAD).
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listMLBTeams
      responses:
        200:
          description: 30 MLB teams with roster counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        abbreviation:
                          type: string
                          example: NYY
                        full_name:
                          type: string
                          example: New York Yankees
                        roster_size:
                          type: integer
                          example: 26
                        active_players:
                          type: integer
                          example: 24
                        positions:
                          type: array
                          items:
                            type: string
                          example:
                            - 1B
                            - 2B
                            - OF
                            - SP
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/mlb/teams/{team}/roster":
    get:
      tags:
        - MLB
      summary: MLB team roster
      description: |
          Returns the active roster for a specific team. Filter by position to pull only starting pitchers or corner infielders for lineup construction.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getMLBTeamRoster
      parameters:
        - name: team
          in: path
          required: true
          description: 3-letter MLB team abbreviation (e.g. NYY, LAD)
          schema:
            type: string
            minLength: 2
            maxLength: 3
          example: NYY
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - SP
              - RP
              - C
              - 1B
              - 2B
              - 3B
              - SS
              - OF
              - DH
          example: SP
      responses:
        200:
          description: Team roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  team:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MLBPlayer"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Team abbreviation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/mlb/games:
    get:
      tags:
        - MLB
      summary: Live and scheduled MLB games
      description: |
          Live inning-by-inning game state from the MLB Stats API pipeline. Defaults to today's games. Scores update on a polling cycle throughout the game day.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listMLBGames
      parameters:
        - name: date
          in: query
          description: Game date (YYYY-MM-DD, defaults to today)
          schema:
            type: string
            format: date
          example: 2026-05-01
        - name: state
          in: query
          description: Filter by game state (matches the live state column exactly)
          schema:
            type: string
            enum:
              - pre_game
              - scheduled
              - in_progress
              - final
              - completed
              - postponed
          example: in_progress
        - name: limit
          in: query
          description: Max games (default 30, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
          example: 30
      responses:
        200:
          description: MLB game states
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MLBGame"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/mlb/standings:
    get:
      tags:
        - MLB
      summary: MLB division standings
      description: |
          Current MLB standings by division sourced from ESPN. Includes win %, streak, home/away splits, and runs differential.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getMLBStandings
      parameters:
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
        - name: division
          in: query
          description: "Filter by division name (partial match: \"AL East\", \"NL West\")"
          schema:
            type: string
          example: AL East
      responses:
        200:
          description: MLB standings by division
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  season:
                    type: integer
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNStanding"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/mlb/scoring/leaders:
    get:
      tags:
        - MLB
      summary: MLB fantasy scoring leaders (Pro)
      description: |
          Top fantasy scorers for any game day, ranked by total points. Uses the PlayCaller scoring engine with standard roto weights (H, HR, RBI, SB, R, BB for batters; IP, K, SV for pitchers).
          
          Useful for identifying daily stack targets and late-swap pivots before lock.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getMLBScoringLeaders
      parameters:
        - name: date
          in: query
          description: Game date (YYYY-MM-DD, defaults to most recent game day)
          schema:
            type: string
            format: date
          example: 2026-05-01
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - SP
              - RP
              - C
              - 1B
              - 2B
              - 3B
              - SS
              - OF
              - DH
          example: OF
        - name: team
          in: query
          description: 3-letter team abbreviation
          schema:
            type: string
          example: NYY
        - name: limit
          in: query
          description: Max leaders (default 25, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          example: 25
      responses:
        200:
          description: Fantasy scoring leaderboard for date
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MLBPlayerStats"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/mlb/scoring/categories:
    get:
      tags:
        - MLB
      summary: MLB rotisserie category leaders (Pro)
      description: |
          Top 10 players per rotisserie scoring category (HR, RBI, SB, R, BB, IP, K, SV) for a given date. Ideal for roto league managers tracking category races and daily contributions.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getMLBScoringCategories
      parameters:
        - name: date
          in: query
          description: Game date (YYYY-MM-DD, defaults to most recent game day)
          schema:
            type: string
            format: date
          example: 2026-05-01
      responses:
        200:
          description: Top 10 per rotisserie category
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  categories:
                    type: object
                    description: "Keys: home_runs, rbi, stolen_bases, runs, walks, innings_pitched, strikeouts, saves"
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        properties:
                          rank:
                            type: integer
                            example: 1
                          id:
                            type: string
                            example: pc_mlb_672640
                          player_name:
                            type: string
                          team:
                            type: string
                          position:
                            type: string
                          value:
                            type: number
                            example: 1
                          stat_date:
                            type: string
                            format: date-time
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nba/games:
    get:
      tags:
        - NBA
      summary: NBA game scores and schedule
      description: |
          Live scores and scheduled NBA games from the ESPN feed. Includes venue, broadcast network, period clock, and team logos for display-ready integrations.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listNBAGames
      parameters:
        - name: date
          in: query
          description: Game date (YYYY-MM-DD, defaults to today)
          schema:
            type: string
            format: date
          example: 2026-05-01
        - name: state
          in: query
          description: Game state filter (matches the live state column exactly)
          schema:
            type: string
            enum:
              - scheduled
              - in_progress
              - final
          example: in_progress
        - name: limit
          in: query
          description: Max games (default 30, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
          example: 30
      responses:
        200:
          description: NBA game states
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNGame"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nba/standings:
    get:
      tags:
        - NBA
      summary: NBA conference standings
      description: |
          Current NBA standings including conference, division, win %, streak, and home/away split records. Filterable by conference.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNBAStandings
      parameters:
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
        - name: conference
          in: query
          description: Filter by conference
          schema:
            type: string
            enum:
              - East
              - West
          example: East
      responses:
        200:
          description: NBA standings by conference
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  season:
                    type: integer
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNStanding"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nba/teams:
    get:
      tags:
        - NBA
      summary: All 30 NBA teams
      description: |
          All 30 NBA teams with conference, division, and ESPN team logo URL. Filterable by conference.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listNBATeams
      parameters:
        - name: conference
          in: query
          description: Filter by conference
          schema:
            type: string
            enum:
              - East
              - West
          example: West
      responses:
        200:
          description: NBA teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          nullable: true
                          example: "2"
                        abbreviation:
                          type: string
                          example: BOS
                        full_name:
                          type: string
                          example: Boston Celtics
                        conference:
                          type: string
                          nullable: true
                          example: East
                        division:
                          type: string
                          nullable: true
                          example: Atlantic
                        logo:
                          type: string
                          format: uri
                          nullable: true
                        record:
                          type: object
                          properties:
                            wins:
                              type: integer
                              nullable: true
                            losses:
                              type: integer
                              nullable: true
                            win_pct:
                              type: number
                              nullable: true
                        last_updated:
                          type: string
                          format: date-time
                          nullable: true
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nba/players:
    get:
      tags:
        - NBA
      summary: NBA players (3,252 seeded)
      description: |
          3,252 NBA players from player_identities (same identity-resolution pipeline as MLB). Searchable by name, position, or team. No jersey number or headshot URL is currently returned (despite earlier docs claiming otherwise — corrected 2026-06-24 against a live response).
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listNBAPlayers
      parameters:
        - name: search
          in: query
          description: Partial player name (case-insensitive)
          schema:
            type: string
          example: LeBron
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - PG
              - SG
              - SF
              - PF
              - C
          example: PG
        - name: team
          in: query
          description: 3-letter team abbreviation
          schema:
            type: string
          example: LAL
        - name: limit
          in: query
          description: Max results (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        200:
          description: NBA players
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  total:
                    type: integer
                  count:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: pc_nba_1262
                        full_name:
                          type: string
                        first_name:
                          type: string
                        last_name:
                          type: string
                        position:
                          type: string
                          nullable: true
                        team:
                          type: string
                        status:
                          type: string
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/nba/players/{id}":
    get:
      tags:
        - NBA
      summary: NBA player profile by ID
      description: |
          Full profile for a single NBA player by PlayCaller ID. Returns platform IDs, team, position, and status.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNBAPlayer
      parameters:
        - name: id
          in: path
          required: true
          description: "PlayCaller NBA player ID (format: pc_nba_XXXXXX)"
          schema:
            type: string
          example: pc_nba_1262
      responses:
        200:
          description: NBA player profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      full_name:
                        type: string
                      first_name:
                        type: string
                      last_name:
                        type: string
                      position:
                        type: string
                        nullable: true
                      team:
                        type: string
                      status:
                        type: string
                      metadata:
                        type: object
                        nullable: true
                      last_updated:
                        type: string
                        format: date-time
                        nullable: true
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Player not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/nba/players/{id}/stats":
    get:
      tags:
        - NBA
      summary: Game-by-game stats for an NBA player
      description: |
          Game logs from `historical_performance` for an NBA player (127,909 rows across 5 seasons, 2021–2025). Returns fantasy points and box score stats per game.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNBAPlayerStats
      parameters:
        - name: id
          in: path
          required: true
          description: PlayCaller NBA player ID
          schema:
            type: string
          example: pc_nba_1262
        - name: season
          in: query
          description: Season year (2021–2025)
          schema:
            type: integer
          example: 2025
        - name: limit
          in: query
          description: Max game logs (default 30, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 30
          example: 30
      responses:
        200:
          description: NBA game log
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  player:
                    type: object
                    properties:
                      id:
                        type: string
                      full_name:
                        type: string
                      position:
                        type: string
                      team:
                        type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/HistoricalGameRecord"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Player not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/nba/teams/{team}/roster":
    get:
      tags:
        - NBA
      summary: NBA team roster
      description: |
          Active roster for a specific NBA team. Returns all players from `player_identities` for the requested team abbreviation.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNBATeamRoster
      parameters:
        - name: team
          in: path
          required: true
          description: 3-letter NBA team abbreviation (e.g. BOS, LAL)
          schema:
            type: string
            minLength: 2
            maxLength: 3
          example: BOS
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - PG
              - SG
              - SF
              - PF
              - C
          example: PG
      responses:
        200:
          description: Team roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  team:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        full_name:
                          type: string
                        position:
                          type: string
                          nullable: true
                        status:
                          type: string
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Team abbreviation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nba/confidence:
    get:
      tags:
        - NBA
      summary: NBA confidence model — raw score + components (Pro Insights, AUC 0.855)
      description: |
          Full detail behind PlayCaller's best-validated signal in the entire portfolio — AUC-ROC 0.855, 84.23x decile lift, promoted ACTIVE 2026-06-19. `/v1/feed` returns a capped display score for this same model; this endpoint exposes the raw (pre-cap) score, percentile, and the 5 underlying signal components including `usage_vacuum`.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getNBAConfidence
      parameters:
        - name: player
          in: query
          required: true
          description: Player full name (fuzzy matched)
          schema:
            type: string
          example: Nikola Jokic
      responses:
        200:
          description: NBA confidence score with raw detail and model audit citation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  player:
                    type: string
                  team:
                    type: string
                    nullable: true
                  position:
                    type: string
                    nullable: true
                  confirmed_out:
                    type: boolean
                  reason:
                    type: string
                    nullable: true
                    description: "Present when confidence is null: \"insufficient game history\", \"unsupported position (X)\", or a disqualification reason"
                  confidence:
                    type: object
                    nullable: true
                    properties:
                      score:
                        type: number
                        example: 43
                      display:
                        type: string
                        example: 43%
                      tier:
                        type: string
                        example: strong
                      label:
                        type: string
                        example: Strong Start
                      signals:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                            label:
                              type: string
                            value:
                              type: number
                            direction:
                              type: string
                              enum:
                                - up
                                - down
                                - flat
                            note:
                              type: string
                      raw:
                        type: object
                        description: Pre-display-cap detail — the actual differentiator this endpoint sells over /v1/feed’s capped summary
                        properties:
                          raw_features:
                            type: array
                            items:
                              type: number
                          normed_features:
                            type: array
                            items:
                              type: number
                          z:
                            type: number
                          raw_logit:
                            type: number
                          calibrated:
                            type: number
                          raw_pct:
                            type: number
                            example: 43
                          capped_pct:
                            type: number
                            example: 43
                          display_cap:
                            type: number
                            example: 55
                          was_capped:
                            type: boolean
                  model_audit:
                    type: object
                    properties:
                      auc:
                        type: number
                        example: 0.855
                      decile_lift:
                        type: number
                        example: 84.23
                      model_type:
                        type: string
                        example: confidence
                      sport:
                        type: string
                        example: NBA
                      validated:
                        type: string
                        format: date
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        404:
          description: Player not found or not an NBA player
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nfl/teams:
    get:
      tags:
        - NFL
      summary: All 32 NFL teams
      description: |
          Returns metadata for all 32 NFL teams including conference, division, and live roster counts from `player_identities`.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listNFLTeams
      parameters:
        - name: conference
          in: query
          description: Filter by conference
          schema:
            type: string
            enum:
              - AFC
              - NFC
          example: AFC
        - name: division
          in: query
          description: "Filter by division (partial match: \"North\", \"AFC West\")"
          schema:
            type: string
          example: North
      responses:
        200:
          description: 32 NFL teams with roster counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        abbreviation:
                          type: string
                          example: KC
                        full_name:
                          type: string
                          example: Kansas City Chiefs
                        city:
                          type: string
                          example: Kansas City
                        nickname:
                          type: string
                          example: Chiefs
                        conference:
                          type: string
                          example: AFC
                        division:
                          type: string
                          example: AFC West
                        player_count:
                          type: integer
                          example: 53
                        roster_url:
                          type: string
                          example: /v1/nfl/teams/KC/roster
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/nfl/teams/{team}/roster":
    get:
      tags:
        - NFL
      summary: NFL team roster
      description: |
          Active roster for a specific NFL team from `player_identities`. Filter by position to pull only QBs, WRs, or RBs.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNFLTeamRoster
      parameters:
        - name: team
          in: path
          required: true
          description: 2-3 letter NFL team abbreviation (e.g. KC, NE, SF)
          schema:
            type: string
            minLength: 2
            maxLength: 3
          example: KC
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - QB
              - RB
              - WR
              - TE
              - K
              - DEF
              - DL
              - LB
              - DB
              - OL
          example: WR
      responses:
        200:
          description: Team roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  team:
                    type: object
                    properties:
                      abbreviation:
                        type: string
                      full_name:
                        type: string
                      conference:
                        type: string
                      division:
                        type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: pc_nfl_001234
                        full_name:
                          type: string
                        position:
                          type: string
                        status:
                          type: string
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Team abbreviation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nfl/players:
    get:
      tags:
        - NFL
      summary: NFL players
      description: |
          All NFL players from the canonical `player_identities` table. Searchable by name, position, or team. Same identity-resolution pipeline as MLB and NBA.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listNFLPlayers
      parameters:
        - name: search
          in: query
          description: Partial player name (case-insensitive)
          schema:
            type: string
          example: Mahomes
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
            enum:
              - QB
              - RB
              - WR
              - TE
              - K
              - DEF
          example: WR
        - name: team
          in: query
          description: 2-3 letter team abbreviation
          schema:
            type: string
          example: KC
        - name: limit
          in: query
          description: Max results (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        200:
          description: NFL players
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  total:
                    type: integer
                  count:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: pc_nfl_001234
                        full_name:
                          type: string
                        first_name:
                          type: string
                        last_name:
                          type: string
                        position:
                          type: string
                        team:
                          type: string
                        status:
                          type: string
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/nfl/players/{id}":
    get:
      tags:
        - NFL
      summary: NFL player profile by ID
      description: |
          Full profile for a single NFL player including team metadata, conference/division, and platform-resolved status.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNFLPlayer
      parameters:
        - name: id
          in: path
          required: true
          description: "PlayCaller NFL player ID (format: pc_nfl_XXXXXX)"
          schema:
            type: string
          example: pc_nfl_001234
      responses:
        200:
          description: NFL player profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      full_name:
                        type: string
                      first_name:
                        type: string
                      last_name:
                        type: string
                      position:
                        type: string
                      team:
                        type: string
                      team_name:
                        type: string
                        nullable: true
                      conference:
                        type: string
                        nullable: true
                      division:
                        type: string
                        nullable: true
                      status:
                        type: string
                      metadata:
                        type: object
                        nullable: true
                      last_updated:
                        type: string
                        format: date-time
                        nullable: true
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Player not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/nfl/players/{id}/stats":
    get:
      tags:
        - NFL
      summary: Weekly game log for an NFL player
      description: |
          Game-by-game stat lines from `historical_performance`. Covers NFL 2024 full season (weeks 1–18, ~4,400 records). Returns passing/rushing/receiving splits and fantasy points.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNFLPlayerStats
      parameters:
        - name: id
          in: path
          required: true
          description: PlayCaller NFL player ID
          schema:
            type: string
          example: pc_nfl_001234
        - name: season
          in: query
          description: "Season year (default: all available)"
          schema:
            type: integer
          example: 2024
        - name: week
          in: query
          description: NFL week number (1–18)
          schema:
            type: integer
            minimum: 1
            maximum: 18
          example: 8
        - name: limit
          in: query
          description: Max game logs (default 30, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 30
          example: 30
      responses:
        200:
          description: Weekly game log
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  player:
                    type: object
                    properties:
                      id:
                        type: string
                      full_name:
                        type: string
                      position:
                        type: string
                      team:
                        type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        season:
                          type: integer
                        week:
                          type: integer
                        team:
                          type: string
                        opponent:
                          type: string
                          nullable: true
                        position:
                          type: string
                        passing:
                          type: object
                          properties:
                            yards:
                              type: integer
                              nullable: true
                            tds:
                              type: integer
                              nullable: true
                        rushing:
                          type: object
                          properties:
                            yards:
                              type: integer
                              nullable: true
                            tds:
                              type: integer
                              nullable: true
                        receiving:
                          type: object
                          properties:
                            yards:
                              type: integer
                              nullable: true
                            tds:
                              type: integer
                              nullable: true
                            receptions:
                              type: integer
                              nullable: true
                        snap_pct:
                          type: number
                          nullable: true
                        target_share:
                          type: number
                          nullable: true
                        air_yards:
                          type: number
                          nullable: true
                        fantasy_points:
                          type: number
                          nullable: true
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Player not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nfl/games:
    get:
      tags:
        - NFL
      summary: NFL schedule and scores
      description: |
          NFL schedule and game results from `nfl_games`. Covers the 2026 season (285 games scheduled) with 2024 results backfilled. Filter by season, week, or status.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listNFLGames
      parameters:
        - name: season
          in: query
          description: "Season year (default: all)"
          schema:
            type: integer
          example: 2026
        - name: week
          in: query
          description: NFL week number
          schema:
            type: integer
            minimum: 1
            maximum: 22
          example: 1
        - name: status
          in: query
          description: Game status filter
          schema:
            type: string
            enum:
              - scheduled
              - in_progress
              - final
          example: final
        - name: limit
          in: query
          description: Max games (default 30, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
          example: 30
      responses:
        200:
          description: NFL games
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        game_id:
                          type: string
                        season:
                          type: integer
                        week:
                          type: integer
                        season_type:
                          type: string
                          example: regular
                        game_time:
                          type: string
                          format: date-time
                          nullable: true
                        status:
                          type: string
                        away_team:
                          type: object
                          properties:
                            name:
                              type: string
                            abbreviation:
                              type: string
                        home_team:
                          type: object
                          properties:
                            name:
                              type: string
                            abbreviation:
                              type: string
                        away_score:
                          type: integer
                          nullable: true
                        home_score:
                          type: integer
                          nullable: true
                        winner:
                          type: string
                          nullable: true
                        spread:
                          type: number
                          nullable: true
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nfl/standings:
    get:
      tags:
        - NFL
      summary: NFL division standings
      description: |
          NFL division standings computed from `nfl_games` results (W/L/T record, win %). Grouped by conference and division.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNFLStandings
      parameters:
        - name: conference
          in: query
          description: Filter by conference
          schema:
            type: string
            enum:
              - AFC
              - NFC
          example: AFC
        - name: division
          in: query
          description: "Filter by division (partial match: \"AFC West\")"
          schema:
            type: string
          example: AFC West
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
      responses:
        200:
          description: NFL standings by division
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  season:
                    type: integer
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        team:
                          type: string
                          example: KC
                        full_name:
                          type: string
                          example: Kansas City Chiefs
                        conference:
                          type: string
                          example: AFC
                        division:
                          type: string
                          example: AFC West
                        wins:
                          type: integer
                        losses:
                          type: integer
                        ties:
                          type: integer
                        win_pct:
                          type: number
                          format: float
                          example: 0.75
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/{sport}/players/{id}/alpha":
    get:
      tags:
        - Multi
      summary: Alpha Metrics for a player (Pro Insights+)
      description: |
          Returns three proprietary ML-derived signals computed from the player's last 8 games:
          
          - **Consistency Score (0–100)** — how stable the player's usage/floor is. Higher = more reliable starter.
          - **Momentum Delta** — signed float. Positive = trending up vs. prior 3-game baseline; negative = cooling off.
          - **Opportunity Ceiling** — 90th-percentile fantasy output from the sample window. Represents the player's peak upside.
          
          Results are pre-computed weekly (Tuesday 3 AM ET, post-MNF) and cached. Fresh players compute on-the-fly.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getPlayerAlphaMetrics
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sport
          in: path
          required: true
          description: Sport key
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
          example: nfl
        - name: id
          in: path
          required: true
          description: PlayCaller player ID
          schema:
            type: string
          example: pc_nfl_001234
      responses:
        200:
          description: Alpha Metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      player_id:
                        type: string
                        example: pc_nfl_001234
                      full_name:
                        type: string
                        example: CeeDee Lamb
                      position:
                        type: string
                        example: WR
                      team:
                        type: string
                        example: DAL
                      sport:
                        type: string
                        example: nfl
                      consistency_score:
                        type: number
                        nullable: true
                        minimum: 0
                        maximum: 100
                        description: Usage/floor stability (0–100). Higher = more consistent starter.
                        example: 78
                      momentum_delta:
                        type: number
                        nullable: true
                        description: Avg pts last 3 games minus avg games 4–6 back. Positive = trending up.
                        example: 4.2
                      opportunity_ceiling:
                        type: number
                        nullable: true
                        description: 90th-percentile fantasy output from the last 8 games. Peak upside.
                        example: 38.4
                      sample_size:
                        type: integer
                        example: 8
                      season:
                        type: integer
                        example: 2024
                      week_computed:
                        type: integer
                        nullable: true
                        example: 14
                      computed_at:
                        type: string
                        format: date-time
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro Insights or Syndicate Alpha key required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        404:
          description: Insufficient data (< 4 historical games)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/players/similar/{id}":
    get:
      tags:
        - Multi
      summary: Find players with similar stat profiles (Pro Insights+)
      description: |
          Returns the N most similar players by cosine distance across an 8-dimension stat-profile vector:
          
          1. Average fantasy points
          2. Usage rate (snap% for NFL, minutes for NBA)
          3. Opportunity rate (target share for NFL, usage% for NBA)
          4. Average rushing yards
          5. Average receiving yards
          6. Consistency Score (from Alpha Metrics)
          7. Momentum Delta (normalized)
          8. Opportunity Ceiling (from Alpha Metrics)
          
          Use case: "Find WRs with the same profile as CeeDee Lamb," "Identify breakout candidates with similar usage to Cooper Kupp Year 2," DFS stack-building, dynasty trade comps.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getSimilarPlayers
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: PlayCaller player ID to find comps for
          schema:
            type: string
          example: pc_nfl_001234
        - name: sport
          in: query
          required: true
          description: Sport key (required — similarity is sport-scoped)
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
          example: nfl
        - name: limit
          in: query
          description: Number of similar players (default 10, max 25)
          schema:
            type: integer
            minimum: 1
            maximum: 25
            default: 10
          example: 10
      responses:
        200:
          description: Similar players ranked by cosine similarity
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  query:
                    type: object
                    properties:
                      player_id:
                        type: string
                      full_name:
                        type: string
                      position:
                        type: string
                      team:
                        type: string
                      sport:
                        type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        full_name:
                          type: string
                        position:
                          type: string
                        team:
                          type: string
                        similarity_score:
                          type: number
                          minimum: -1
                          maximum: 1
                          description: 1.0 = identical profile, 0.0 = no overlap
                          example: 0.9342
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: sport parameter missing or invalid
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro Insights or Syndicate Alpha key required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        404:
          description: Player not found or insufficient game data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/events/stream:
    get:
      tags:
        - Multi
      summary: Real-time SSE event stream (Pro Insights+)
      description: |
          Server-Sent Events stream delivering live sports intelligence as it happens. Keep the connection open and receive events pushed by the server.
          
          **Events pushed:**
          - `player.injured` — new injury signal detected
          - `game.score_updated` — live score change
          - `game.status_changed` — game state transition (scheduled → in_progress → final)
          - `anomaly.detected` — statistical anomaly flagged
          
          Heartbeat `:heartbeat` comment sent every 30s to keep the connection alive.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: streamEvents
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sport
          in: query
          description: "Filter to a single sport (default: all)"
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
              - all
          example: nfl
      responses:
        200:
          description: SSE stream (text/event-stream)
          content:
            text/event-stream:
              schema:
                type: string
                example: |
                    event: player.injured
                    data: {"event":"player.injured","sport":"nfl","player_name":"Patrick Mahomes","team":"KC","status":"Questionable","injury_type":"Ankle","ts":"2026-07-02T22:00:00Z"}
                    
                    
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro Insights or Syndicate Alpha key required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /daas/webhooks:
    post:
      tags:
        - Account
      summary: Register a webhook endpoint (Syndicate Alpha)
      description: |
          Register an HTTPS endpoint to receive signed webhook deliveries for one or more event types. Returns a one-time secret for HMAC-SHA256 signature verification (`X-PlayCaller-Signature`).
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: createWebhook
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - events
              properties:
                url:
                  type: string
                  format: uri
                  example: "https://your-server.com/playcaller-hook"
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - player.injured
                      - game.score_updated
                      - game.status_changed
                      - anomaly.detected
                  example:
                    - player.injured
                    - anomaly.detected
      responses:
        201:
          description: Webhook registered. Secret shown once.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      url:
                        type: string
                      events:
                        type: array
                        items:
                          type: string
                      secret:
                        type: string
                        description: HMAC secret — store securely, not shown again
                      created_at:
                        type: string
                        format: date-time
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Syndicate Alpha key required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      tags:
        - Account
      summary: List registered webhooks (Syndicate Alpha)
      operationId: listWebhooks
      security:
        - ApiKeyAuth: []
      responses:
        200:
          description: Active and inactive webhooks for this key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        url:
                          type: string
                        events:
                          type: array
                          items:
                            type: string
                        is_active:
                          type: boolean
                        failure_count:
                          type: integer
                        last_delivery_at:
                          type: string
                          format: date-time
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Syndicate Alpha key required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/daas/webhooks/{id}":
    delete:
      tags:
        - Account
      summary: Deactivate a webhook (Syndicate Alpha)
      operationId: deleteWebhook
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Webhook deactivated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/daas/webhooks/{id}/deliveries":
    get:
      tags:
        - Account
      summary: Webhook delivery log (Syndicate Alpha)
      description: Returns the last 50 delivery attempts for a webhook, including status codes, attempt counts, and error messages.
      operationId: getWebhookDeliveries
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Delivery log
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook_id:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        event_type:
                          type: string
                        status_code:
                          type: integer
                          nullable: true
                        attempt:
                          type: integer
                        delivered_at:
                          type: string
                          format: date-time
                        error_message:
                          type: string
                          nullable: true
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/players/search:
    get:
      tags:
        - Multi
      summary: Cross-sport player search
      description: |
          Search across all 13,606 canonical player identities (NFL + MLB + NBA) by name, with optional sport and position filters. Returns matching players from all sports in a single call.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: searchPlayers
      parameters:
        - name: q
          in: query
          required: true
          description: Player name search (min 2 characters)
          schema:
            type: string
            minLength: 2
          example: LeBron
        - name: sport
          in: query
          description: Filter by sport
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
          example: nba
        - name: position
          in: query
          description: Filter by position
          schema:
            type: string
          example: WR
        - name: limit
          in: query
          description: Max results (default 25, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          example: 25
      responses:
        200:
          description: Matching player identities across all sports
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  q:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PlayerIdentity"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: Missing or too-short q parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/trending:
    get:
      tags:
        - Multi
      summary: Trending hashtags/topics (all tiers, including free Sandbox)
      description: |
          Raw trending-topic rows refreshed on a ~2-hour cadence. Contextual social signal, not a model output — no tier gate.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getTrending
      parameters:
        - name: sport
          in: query
          description: Filter by sport (omit or "all" for everything)
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
              - all
          example: nba
      responses:
        200:
          description: Trending topics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        tag:
                          type: string
                        sport:
                          type: string
                        category:
                          type: string
                        relevance_score:
                          type: integer
                        scraped_at:
                          type: string
                          format: date-time
                        expires_at:
                          type: string
                          format: date-time
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/articles/waiver:
    get:
      tags:
        - Multi
      summary: Waiver wire articles with signal audit trail (Pro Insights)
      description: |
          AI-generated waiver-wire recommendations alongside `signals_used` — the exact validated model-signal rows, with their own AUCs, that drove each call. No other sports-data API exposes which signals produced a given recommendation.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getWaiverArticles
      parameters:
        - name: sport
          in: query
          required: true
          description: Sport
          schema:
            type: string
            enum:
              - nfl
              - mlb
              - nba
          example: nfl
        - name: season
          in: query
          description: Season year
          schema:
            type: integer
          example: 2026
        - name: week
          in: query
          description: Week number
          schema:
            type: integer
          example: 10
        - name: limit
          in: query
          description: Max articles (default 10, max 50)
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          example: 10
      responses:
        200:
          description: Waiver wire articles with signal audit trail
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        slug:
                          type: string
                        title:
                          type: string
                        content:
                          type: string
                        meta_description:
                          type: string
                          nullable: true
                        season:
                          type: integer
                        week:
                          type: integer
                        signals_used:
                          type: array
                          description: Validated model-signal rows that produced this article
                        published_at:
                          type: string
                          format: date-time
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: Missing required sport parameter
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  "/v1/{sport}/games/history":
    get:
      tags:
        - Multi
      summary: Raw per-game historical box lines (Pro Insights)
      description: |
          `/analytics/trends` only returns aggregated trend summaries; this exposes the granular per-game rows behind those — `historical_performance` for NFL/NBA, `daily_player_stats` for MLB.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getGamesHistory
      parameters:
        - name: sport
          in: path
          required: true
          description: Sport
          schema:
            type: string
            enum:
              - nfl
              - nba
              - mlb
          example: nfl
        - name: player_name
          in: query
          description: Partial match (ILIKE)
          schema:
            type: string
          example: Josh Allen
        - name: season
          in: query
          description: Season year
          schema:
            type: integer
          example: 2025
        - name: limit
          in: query
          description: Max rows (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
      responses:
        200:
          description: Raw per-game rows for the requested sport
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  sport:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        404:
          description: Unsupported sport (must be nfl, nba, or mlb)
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/cfb/games:
    get:
      tags:
        - CFB
      summary: College football scoreboard (Pro)
      description: |
          CFB game scores and schedule from ESPN. Covers FBS games including conference championships and bowl games.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listCFBGames
      parameters:
        - name: date
          in: query
          description: Game date (YYYY-MM-DD)
          schema:
            type: string
            format: date
          example: 2026-09-05
        - name: state
          in: query
          description: Game state filter (matches the live state column exactly)
          schema:
            type: string
            enum:
              - scheduled
              - in_progress
              - final
          example: final
        - name: limit
          in: query
          description: Max games (default 50, max 200)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
      responses:
        200:
          description: CFB games
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNGame"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/cfb/standings:
    get:
      tags:
        - CFB
      summary: College football conference standings (Pro)
      description: |
          CFB standings by conference. Includes win %, conference record, and streak. Useful for playoff scenario modeling.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getCFBStandings
      parameters:
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
        - name: conference
          in: query
          description: "Filter by conference (partial match: \"SEC\", \"Big Ten\")"
          schema:
            type: string
          example: SEC
      responses:
        200:
          description: CFB standings
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  season:
                    type: integer
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNStanding"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/cfb/rankings:
    get:
      tags:
        - CFB
      summary: AP / Coaches Poll / CFP rankings (Pro)
      description: |
          AP Top 25, Coaches Poll, and CFP rankings by week. Each poll returns ranked teams with first-place votes, total points, and previous rank movement.
          
          **Tier access:** Pro Insights, Syndicate Alpha
      operationId: getCFBRankings
      parameters:
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
        - name: poll
          in: query
          description: "Poll filter (partial match: \"AP\", \"Coaches\", \"CFP\")"
          schema:
            type: string
          example: AP
        - name: week
          in: query
          description: Week number (1–16)
          schema:
            type: integer
            minimum: 1
            maximum: 16
          example: 14
      responses:
        200:
          description: CFB rankings grouped by poll
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  season:
                    type: integer
                  polls:
                    type: object
                    description: Keys are poll names; values are ranked team arrays
                    additionalProperties:
                      type: array
                      items:
                        $ref: "#/components/schemas/CFBRanking"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        403:
          description: Pro tier required for this endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: TIER_INSUFFICIENT
                message: This endpoint requires a Pro subscription.
                documentation_url: "https://playcallerapp.com/developer/docs/tiers"
                upgrade_url: "https://playcallerapp.com/developer/checkout?tier=pro"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/soccer/games:
    get:
      tags:
        - Soccer
      summary: Soccer match scores (EPL + MLS)
      description: |
          Live and historical match scores for EPL and MLS. Includes team logos, venue, broadcast, and score state for display-ready applications.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listSoccerGames
      parameters:
        - name: league
          in: query
          description: League filter (omit for both leagues)
          schema:
            type: string
            enum:
              - epl
              - mls
          example: epl
        - name: date
          in: query
          description: Match date (YYYY-MM-DD, defaults to today)
          schema:
            type: string
            format: date
          example: 2026-05-01
        - name: state
          in: query
          description: Game state filter (matches the live state column exactly)
          schema:
            type: string
            enum:
              - scheduled
              - in_progress
              - final
          example: final
        - name: limit
          in: query
          description: Max matches (default 30, max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
          example: 30
      responses:
        200:
          description: Soccer matches
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNGame"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/soccer/standings:
    get:
      tags:
        - Soccer
      summary: Soccer league table (EPL, MLS, La Liga, Bundesliga, Serie A, UCL)
      description: |
          Current league tables for EPL, MLS, La Liga, Bundesliga, Serie A, and Champions League. Includes points, goal difference, wins, draws, losses, and home/away splits.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getSoccerStandings
      parameters:
        - name: league
          in: query
          description: League filter (epl, mls, la_liga, bundesliga, serie_a, champions_league; omit for all)
          schema:
            type: string
            enum:
              - epl
              - mls
              - la_liga
              - bundesliga
              - serie_a
              - champions_league
          example: epl
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
      responses:
        200:
          description: Soccer standings
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  league:
                    type: string
                    example: epl
                  season:
                    type: integer
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNStanding"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nhl/games:
    get:
      tags:
        - NHL
      summary: NHL game scores and schedule
      description: |
          Current day scores, live updates, and upcoming schedule for NHL games. Polled every 30 min during game windows.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNHLGames
      parameters:
        - name: date
          in: query
          description: Game date (YYYY-MM-DD or 'today')
          schema:
            type: string
          example: today
        - name: state
          in: query
          description: Filter by game state (in_progress, final, scheduled)
          schema:
            type: string
        - name: limit
          in: query
          description: Max results (default 50, max 200)
          schema:
            type: integer
          example: 50
      responses:
        200:
          description: NHL games
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNGame"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/nhl/standings:
    get:
      tags:
        - NHL
      summary: NHL standings by division
      description: |
          Current NHL standings including wins, losses, OT losses, points, and division/conference breakdown.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getNHLStandings
      parameters:
        - name: season
          in: query
          description: Season year (defaults to current)
          schema:
            type: integer
          example: 2026
        - name: division
          in: query
          description: Filter by division name (partial match)
          schema:
            type: string
          example: Atlantic
      responses:
        200:
          description: NHL standings
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  season:
                    type: integer
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ESPNStanding"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/tennis/matches:
    get:
      tags:
        - Tennis
      summary: ATP and WTA match scores
      description: |
          Live and completed tennis matches across ATP and WTA tours. Returns player names, set scores, and match status.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getTennisMatches
      parameters:
        - name: tour
          in: query
          description: Tour filter (atp or wta)
          schema:
            type: string
            enum:
              - atp
              - wta
          example: atp
        - name: date
          in: query
          description: Match date (YYYY-MM-DD or 'today')
          schema:
            type: string
          example: today
        - name: state
          in: query
          description: Match state (in_progress, final, scheduled)
          schema:
            type: string
        - name: limit
          in: query
          description: Max results (default 50, max 200)
          schema:
            type: integer
      responses:
        200:
          description: Tennis matches
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        match_id:
                          type: string
                        date:
                          type: string
                        tour:
                          type: string
                        state:
                          type: string
                        player_1:
                          type: string
                        player_2:
                          type: string
                        score_p1:
                          type: integer
                        score_p2:
                          type: integer
                        set:
                          type: integer
                        is_final:
                          type: boolean
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/golf/tournaments:
    get:
      tags:
        - Golf
      summary: Active and recent golf tournaments
      description: |
          Lists current and recently completed PGA Tour and LPGA Tour tournaments with player counts and dates.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getGolfTournaments
      parameters:
        - name: tour
          in: query
          description: Tour filter (pga or lpga)
          schema:
            type: string
            enum:
              - pga
              - lpga
          example: pga
        - name: limit
          in: query
          description: Max tournaments (default 10, max 50)
          schema:
            type: integer
      responses:
        200:
          description: Tournament list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        tournament_id:
                          type: string
                        name:
                          type: string
                        date:
                          type: string
                        tour:
                          type: string
                        is_active:
                          type: boolean
                        player_count:
                          type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/golf/leaderboard:
    get:
      tags:
        - Golf
      summary: Current tournament leaderboard
      description: |
          Live or most recent tournament leaderboard with positions, scores relative to par, and per-round scores. Updated every 4 hours.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getGolfLeaderboard
      parameters:
        - name: tour
          in: query
          description: Tour (pga or lpga)
          schema:
            type: string
            enum:
              - pga
              - lpga
          example: pga
        - name: limit
          in: query
          description: Max players (default 50, max 156)
          schema:
            type: integer
      responses:
        200:
          description: Golf leaderboard
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  tournament:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      date:
                        type: string
                      is_active:
                        type: boolean
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        position:
                          type: integer
                        position_display:
                          type: string
                        player_name:
                          type: string
                        total_score_display:
                          type: string
                        thru_display:
                          type: string
                        rounds:
                          type: object
                          properties:
                            r1:
                              type: integer
                            r2:
                              type: integer
                            r3:
                              type: integer
                            r4:
                              type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/sports:
    get:
      tags:
        - Multi
      summary: Supported sports and endpoint discovery
      description: |
          Returns all supported sports with their available endpoints and status. Use this to programmatically discover which data is live vs. coming soon for your tier.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: listSports
      responses:
        200:
          description: Sports and available endpoints by tier
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  endpoint:
                    type: string
                  sports:
                    type: array
                    items:
                      type: object
                      properties:
                        sport:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                        endpoints:
                          type: array
                          items:
                            type: string
                  cross_sport_endpoints:
                    type: array
                    items:
                      type: string
                    description: Endpoints not scoped to one sport, e.g. /v1/trending, /v1/articles/waiver
                  meta:
                    type: object
                    properties:
                      tier:
                        type: string
                      documentation_url:
                        type: string
                        format: uri
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /daas/usage:
    get:
      tags:
        - Account
      summary: API key quota and usage breakdown
      description: |
          Returns current quota consumption, rate limits, tier details, and per-endpoint call breakdown for the authenticated key. Use this to build usage dashboards or trigger pre-quota alerts in your application.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getDaaSUsage
      responses:
        200:
          description: API key usage statistics — flat object, not wrapped in `data`
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageStats"
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /daas/key-info:
    get:
      tags:
        - Account
      summary: API key metadata
      description: |
          Returns tier, trial status, and creation date for the API key passed as `?key=` query parameter. Useful for building key verification flows in your own applications without exposing the full usage payload.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getDaaSKeyInfo
      parameters:
        - name: key
          in: query
          required: true
          description: The PlayCaller API key to look up
          schema:
            type: string
          example: pc_pro_abc123
      responses:
        200:
          description: API key metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  tier:
                    type: string
                    enum:
                      - sandbox
                      - hobbyist
                      - build
                      - pro
                      - pro_insights
                      - enterprise
                      - syndicate_alpha
                  is_trial:
                    type: boolean
                  trial_days_remaining:
                    type: integer
                    nullable: true
                  created_at:
                    type: string
                    format: date-time
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: Key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /daas/trial/start:
    post:
      tags:
        - Account
      summary: Start a 14-day free trial
      description: |
          Creates a Hobbyist-tier API key for a 14-day free trial. No credit card required. Key is returned in the response and emailed to the provided address. Limit: one trial per email.
          
          **Auth:** No API key required
      operationId: startDaaSTrial
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  example: dev@example.com
                use_case:
                  type: string
                  description: What you are building (optional, helps us improve)
                  example: DFS lineup optimizer for NFL season
      responses:
        200:
          description: Trial key created — full response contains API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  api_key:
                    type: string
                    description: Your new PlayCaller API key. Store it securely.
                    example: pc_hob_xxxxxxxx
                  tier:
                    type: string
                    example: hobbyist
                  trial_ends_at:
                    type: string
                    format: date-time
                  message:
                    type: string
                    example: Your 14-day trial is active. Key emailed to dev@example.com.
        409:
          description: Email already has an active trial or subscription
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        500:
          description: Internal error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /daas/register-key:
    post:
      tags:
        - Account
      summary: Register an existing API key
      description: |
          Associates an existing DaaS API key with a user account for dashboard access. Used internally by the developer dashboard onboarding flow.
          
          **Auth:** No API key required
      operationId: registerDaaSKey
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - api_key
              properties:
                email:
                  type: string
                  format: email
                  example: dev@example.com
                api_key:
                  type: string
                  example: pc_pro_abc123
      responses:
        200:
          description: Key registered to account
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        401:
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: INVALID_API_KEY
                message: The provided API key is invalid or has been revoked.
                documentation_url: "https://playcallerapp.com/developer/docs"
        404:
          description: API key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        429:
          description: Rate limit or monthly quota exceeded
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
              example: 42
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded. Try again in 42 seconds.
                documentation_url: "https://playcallerapp.com/developer/docs/rate-limits"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /mcp:
    get:
      tags:
        - MCP
      summary: MCP server info and tool discovery
      description: |
          Returns human-readable JSON describing the PlayCaller MCP server: endpoint URL, auth method, all available tools with descriptions, and links to documentation.
          
          Point Cursor, Claude Desktop, or any MCP-compatible client at this URL to discover available tools automatically.
          
          **Auth:** No authentication required for GET (tool invocation requires X-PlayCaller-Key)
      operationId: getMCPInfo
      security: []
      responses:
        200:
          description: MCP server info with tool list
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: PlayCaller MCP Server
                  version:
                    type: string
                    example: 1.0.0
                  protocol:
                    type: string
                    example: MCP over HTTP (JSON-RPC 2.0)
                  endpoint:
                    type: string
                    format: uri
                    example: "https://playcallerapp.com/mcp"
                  auth:
                    type: string
                    example: "X-PlayCaller-Key: <your_daas_key>"
                  tools:
                    type: array
                    items:
                      $ref: "#/components/schemas/MCPTool"
                  docs:
                    type: string
                    format: uri
                    example: "https://playcallerapp.com/developer#mcp"
                  get_key:
                    type: string
                    format: uri
                    example: "https://playcallerapp.com/developer#pricing"
    post:
      tags:
        - MCP
      summary: MCP JSON-RPC 2.0 endpoint
      description: |
          The PlayCaller MCP server implements Anthropic's Model Context Protocol over HTTP transport. Send JSON-RPC 2.0 messages to invoke sports intelligence tools from any AI application.
          
          **Available tools (7):**
          - `get_injury_signals` — Active beat reporter signals filtered by sport/severity
          - `get_player_identity` — Resolve a player name or platform ID across ESPN, Sleeper, Yahoo, NFL.com
          - `get_anomaly_scores` — Players with usage patterns deviating from 3-season baseline (score 0–100)
          - `get_prediction_markets` — Active Kalshi prop markets with AI confidence scores
          - `get_player_projections` — AI fantasy point projections using recent game logs and injury signals
          - `get_player_stats` — Game log for any player by name across NFL/MLB/NBA historical_performance
          - `get_team_roster` — Active roster for any team by sport and abbreviation
          
          **Config for Cursor (.cursor/mcp.json):**
          ```json
          {
            "mcpServers": {
              "playcaller": {
                "url": "https://playcallerapp.com/mcp",
                "headers": { "X-PlayCaller-Key": "YOUR_API_KEY" }
              }
            }
          }
          ```
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: invokeMCPTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - method
              properties:
                jsonrpc:
                  type: string
                  enum:
                    - "2.0"
                  example: "2.0"
                id:
                  type: integer
                  example: 1
                method:
                  type: string
                  enum:
                    - initialize
                    - tools/list
                    - tools/call
                    - ping
                  example: tools/call
                params:
                  type: object
                  description: "Required for tools/call: `name` (tool name) and `arguments` (tool-specific args)"
                  properties:
                    name:
                      type: string
                      example: get_injury_signals
                    arguments:
                      type: object
                      example:
                        sport: nfl
                        severity: high
                        limit: 5
            examples:
              listTools:
                summary: List available tools
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: tools/list
              callInjurySignals:
                summary: Get high-severity NFL injuries
                value:
                  jsonrpc: "2.0"
                  id: 2
                  method: tools/call
                  params:
                    name: get_injury_signals
                    arguments:
                      sport: nfl
                      severity: high
                      limit: 5
              resolvePlayer:
                summary: Resolve player identity
                value:
                  jsonrpc: "2.0"
                  id: 3
                  method: tools/call
                  params:
                    name: get_player_identity
                    arguments:
                      name: Christian McCaffrey
                      sport: nfl
      responses:
        200:
          description: JSON-RPC 2.0 response (always 200 — errors returned in body per JSON-RPC spec)
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                    example: "2.0"
                  id:
                    type: integer
                    example: 1
                  result:
                    type: object
                    description: Present on success
                    properties:
                      content:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              example: text
                            text:
                              type: string
                              description: JSON-encoded tool result
                  error:
                    type: object
                    description: Present on error
                    properties:
                      code:
                        type: integer
                        example: -32601
                      message:
                        type: string
                        example: "Method not found: tools/unknown"
  /api/public/stats:
    get:
      tags:
        - Multi
      summary: Platform stats (unauthenticated)
      description: |
          Public endpoint returning live platform statistics: registered users, active signals, total players tracked, sports covered, and platforms integrated. No API key required.
          
          **Tier access:** Developer Sandbox, Build, Pro Insights, Syndicate Alpha
      operationId: getPublicStats
      security: []
      responses:
        200:
          description: Current platform statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicStats"
