openapi: 3.1.0
info:
  title: Anytime Labs API
  version: 1.0.0
  description: API for fetching trending stat insights, and split historical player stats
servers:
  - url: https://api.anytimelabs.io/v1beta
tags:
  - name: Trends
    description: Trend management endpoints
  - name: Game Logs
    description: Game log retrieval and analysis endpoints
  - name: Stat Averages
    description: Stat average management endpoints
  - name: Leagues
    description: League management endpoints
  - name: Teams
    description: Team management endpoints
  - name: Players
    description: Player management endpoints
  - name: Games
    description: Game management endpoints
  - name: Data Filters
    description: Data filter management endpoints
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key required for all endpoints
  responses:
    UnauthorizedError:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    League:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the league
        name:
          type: string
          description: Full name of the league
        sport:
          type: string
          description: Sport for the league (e.g. "baseball")
      required:
        - id
        - name
        - sport
    Player:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the player
        first_name:
          type: string
          description: Player's first name
        last_name:
          type: string
          description: Player's last name
        full_name:
          type: string
          description: Player's full name
        jersey_number:
          type: integer
          description: Player's jersey number
        position:
          $ref: '#/components/schemas/Position'
          description: Player's position
        team:
          $ref: '#/components/schemas/Team'
          description: Player's current team (if applicable)
      required:
        - id
        - first_name
        - last_name
        - full_name
    Team:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the team
        league_id:
          type: string
          description: League identifier
        city:
          type: string
          description: City where the team is based
        mascot:
          type: string
          description: Team's mascot name
        full_name:
          type: string
          description: Full team name
        abbr:
          type: string
          description: Team abbreviation
      required:
        - id
        - city
        - full_name
        - mascot
        - abbr
    Position:
      type: object
      properties:
        category:
          type: string
          description: Logical group for the position
        name:
          type: string
          description: Name of the position
    Game:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the game
        home_team:
          $ref: '#/components/schemas/Team'
          description: Game's home team
        away_team:
          $ref: '#/components/schemas/Team'
          description: Game's away team
        game_time:
          type: string
          description: Game's scheduled time
        league_id:
          type: string
          description: Game's league
      required:
        - id
        - league_id
    EntityType:
      type: string
      enum:
        - player
        - team
      description: Types of entities that can be filtered
    DataFilterValueType:
      type: string
      enum:
        - string
        - integer
        - boolean
        - string_list
        - integer_list
        - null
      description: Allowed type for filter values
    DataFilterType:
      type: string
      enum:
        - time_span
        - game
      description: >-
        Categories of filters. time_span filters segment data by a contiguous
        time period (e.g. last n games, seasons). game filters segment data by a
        specific game condition (e.g. home/away, h2h).
    DataFilterSpec:
      type: object
      properties:
        key:
          type: string
          description: Unique identifier for the filter
        description:
          type: string
          description: Human-readable description of the filter
        value_type:
          $ref: '#/components/schemas/DataFilterValueType'
          description: Allowed value type for this filter
        filter_type:
          $ref: '#/components/schemas/DataFilterType'
          description: Category of the filter
        restricted_to_league_ids:
          type: array
          items:
            type: string
          description: >-
            List of league IDs where this filter is valid. Empty list means it
            is valid for all leagues.
        restricted_to_entity_types:
          type: array
          items:
            $ref: '#/components/schemas/EntityType'
          description: >-
            List of entity types this filter applies to. Empty list means it
            applies to all entity types.
      required:
        - key
        - description
        - value_type
        - filter_type
    DataFilter:
      type: object
      properties:
        key:
          type: string
          description: Unique identifier for the filter
        value:
          type:
            - string
            - integer
            - boolean
            - array
            - 'null'
      required:
        - key
        - value
    TimeSpanAndGameFilters:
      type: object
      properties:
        time_span:
          $ref: '#/components/schemas/DataFilter'
          description: Time span filter to apply
        game_filters:
          type: array
          items:
            $ref: '#/components/schemas/DataFilter'
          description: Optional game-specific filters to apply within the time span
      required:
        - time_span
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    StatResult:
      type: string
      enum:
        - over
        - under
      description: Result of a stat comparison against a handicap
    HitRateStats:
      type: object
      properties:
        side_1_result:
          $ref: '#/components/schemas/StatResult'
          description: Result for the first side of the comparison
        side_2_result:
          $ref: '#/components/schemas/StatResult'
          description: Result for the second side of the comparison
        side_1_hits:
          type: integer
          description: Number of hits for side 1
        side_1_misses:
          type: integer
          description: Number of misses for side 1
        side_2_hits:
          type: integer
          description: Number of hits for side 2
        side_2_misses:
          type: integer
          description: Number of misses for side 2
        pushes:
          type: integer
          description: Number of pushes (ties)
        total:
          type: integer
          description: Total number of comparisons
      required:
        - side_1_result
        - side_2_result
    TrendStats:
      type: object
      properties:
        hits:
          type: integer
          description: Number of times the trend condition was met
        misses:
          type: integer
          description: Number of times the trend condition was not met
        push:
          type: integer
          description: Number of times the trend condition resulted in a push
        total:
          type: integer
          description: Total number of occurrences
        average:
          type: number
          description: Average value for the stat
      required:
        - hits
        - misses
        - push
        - total
        - average
    Trend:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the trend
        league_id:
          type: string
          description: League identifier
        game:
          $ref: '#/components/schemas/Game'
          description: Game this trend applies to
        entity_type:
          $ref: '#/components/schemas/EntityType'
          description: Type of entity this trend applies to
        entity:
          oneOf:
            - $ref: '#/components/schemas/Player'
          description: Entity this trend applies to (currently only players supported)
        stat:
          $ref: '#/components/schemas/StatKey'
          description: Stat key information
        handicap:
          type: number
          format: float
          description: Value to compare the stat against
        stat_result:
          $ref: '#/components/schemas/StatResult'
          description: Result of comparing the stat to the handicap
        entity_trend_stats:
          $ref: '#/components/schemas/TrendStats'
          description: Statistical summary of the trend
        entity_trend_condition:
          $ref: '#/components/schemas/TimeSpanAndGameFilters'
          description: Time span and game filters applied to this trend
        entity_trend_readable_string:
          type: string
          description: Human-readable description of the trend
        updated:
          type: string
          format: date-time
          description: When this trend was last updated
      required:
        - id
        - league_id
        - game
        - entity_type
        - entity
        - stat
        - handicap
        - stat_result
        - entity_trend_stats
        - entity_trend_condition
        - entity_trend_readable_string
        - updated
    StatKey:
      type: object
      properties:
        key:
          type: string
          description: Unique identifier for the stat
        title:
          type: string
          description: Human-readable title for the stat
        entity_type:
          $ref: '#/components/schemas/EntityType'
          description: Type of entity this stat applies to
        position_categories:
          type: array
          items:
            type: string
          description: List of position categories this stat applies to
      required:
        - key
        - title
        - entity_type
        - position_categories
paths:
  /leagues:
    get:
      tags:
        - Leagues
      summary: List all leagues
      responses:
        '200':
          description: List of leagues
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/League'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}:
    get:
      tags:
        - Leagues
      summary: Get League
      description: Fetch necessary information about a league
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: League details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/League'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: League not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/players:
    get:
      tags:
        - Players
      summary: List players
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of players
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Player'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/players/{player_id}:
    get:
      tags:
        - Players
      summary: Get player
      description: Fetch player information including id, name, team, and position
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: player_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Player details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Player not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/players/lookup:
    get:
      tags:
        - Players
      summary: Look player
      description: Search for players by name and optionally by team
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: query
          required: true
          schema:
            type: string
          description: Name to search for (can be partial)
        - name: team_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Optional team ID to filter by. This makes the response faster and
            more accurate.
      responses:
        '200':
          description: List of matching players
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Player'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/teams:
    get:
      tags:
        - Teams
      summary: List teams
      description: List all teams in a league
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/teams/{team_id}:
    get:
      tags:
        - Teams
      summary: Get team
      description: >-
        Fetch team information including id, name, city, mascot, and
        abbreviation
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: team_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Team not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/teams/{team_id}/players:
    get:
      tags:
        - Players
      summary: List team players
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: team_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of players on the team
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Player'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Team not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/games/lookup:
    get:
      tags:
        - Games
      summary: Look up game
      description: Look up a specific game by teams and game time
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: away_team_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the away team
        - name: home_team_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the home team
        - name: game_time
          in: query
          required: true
          schema:
            type: string
          description: Game time in ISO format (YYYY-MM-DDTHH:MM:SSZ)
      responses:
        '200':
          description: Game details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Game'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Game or team not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/games/upcoming:
    get:
      tags:
        - Games
      summary: List upcoming games
      description: Fetch a list of upcoming games for a specific league.
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of upcoming games
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Game'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No upcoming games found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /data-filters:
    get:
      tags:
        - Data Filters
      summary: List data filters
      description: A convenience endpoint to list all available data filters
      responses:
        '200':
          description: List of all data filters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataFilterSpec'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/players/{player_id}/averages:
    post:
      tags:
        - Stat Averages
      summary: Get a player averages
      description: Get a player's averages for the given time span and game filters.
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: player_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conditions:
                  type: array
                  items:
                    $ref: '#/components/schemas/TimeSpanAndGameFilters'
              required:
                - conditions
      responses:
        '200':
          description: Player's average stats for the specified filters
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Player not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /leagues/{league_id}/players/{player_id}/game-logs:
    post:
      tags:
        - Game Logs
      summary: Get player game logs
      description: Fetch player game logs for the given time span and game filters.
      parameters:
        - name: league_id
          in: path
          required: true
          schema:
            type: string
        - name: player_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conditions:
                  type: array
                  items:
                    $ref: '#/components/schemas/TimeSpanAndGameFilters'
                hit_rate_requests:
                  type: array
                  items:
                    type: object
                    properties:
                      stat_key:
                        type: string
                      handicap:
                        type: number
                    required:
                      - stat_key
                      - handicap
                  description: >-
                    Optional array of stat key and handicap pairs to calculate
                    hit rates for
                restrict_reponse_keys_to_hit_rate_requests:
                  type: boolean
                  description: >-
                    If true, only return stats that are referenced in
                    hit_rate_requests
                  default: false
              required:
                - conditions
      responses:
        '200':
          description: Player's game logs and optional hit rate statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  player:
                    $ref: '#/components/schemas/Player'
                  condition_game_logs:
                    type: array
                    items:
                      type: object
                      properties:
                        game_logs:
                          type: array
                          items:
                            type: object
                        averages:
                          type: object
                        hit_rates:
                          type: array
                          items:
                            type: object
                            properties:
                              stat_key:
                                type: string
                              handicap:
                                type: number
                              stats:
                                $ref: '#/components/schemas/HitRateStats'
                              hit_rate_to_calculate_index:
                                type: integer
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Player not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /trends:
    post:
      tags:
        - Trends
      summary: Get trends
      description: >-
        List all available trends matching the specified filters. Filters are
        optional and can be used in any combination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                league_ids:
                  type: array
                  items:
                    type: string
                  description: List of league IDs to filter by
                game_ids:
                  type: array
                  items:
                    type: string
                  description: List of game IDs to filter by
                entity_ids:
                  type: array
                  items:
                    type: string
                  description: List of entity IDs to filter by
                stat_keys:
                  type: array
                  items:
                    type: string
                  description: List of stat keys to filter by
                max_results:
                  type: integer
                  minimum: 1
                  default: 100
                  description: Maximum number of total results to return
                max_results_per_entity:
                  type: integer
                  minimum: 1
                  default: 3
                  description: Maximum number of results to return per entity
                max_results_per_entity_stat_key:
                  type: integer
                  minimum: 1
                  default: 1
                  description: >-
                    Maximum number of results to return per entity and stat key
                    combination
      responses:
        '200':
          description: >-
            List of matching trends. Filters are optional, and listed in order
            from more general to more specific. When providing a filter, it is
            most efficient to provide all filters above it.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Trend'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
