openapi: 3.1.0
info:
  title: BALLDONTLIE - Dota 2 API
  version: 1.0.0
  description: Dota 2 endpoints for the BallDontLie API.
servers:
  - url: https://api.balldontlie.io
    description: Production server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    DotaAbility:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    DotaHero:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        localized_name:
          type: string
    DotaHeroStats:
      type: object
      properties:
        id:
          type: integer
        hero:
          $ref: "#/components/schemas/DotaHero"
        games_count:
          type: integer
        picks_count:
          type: integer
        picks_rate:
          type: number
        wins_count:
          type: integer
        loses_count:
          type: integer
        win_rate:
          type: number
        ban_rate:
          type: number
        early_win_rate:
          type: number
        mid_win_rate:
          type: number
        late_win_rate:
          type: number
        avg_kills:
          type: number
          nullable: true
        avg_deaths:
          type: number
          nullable: true
        avg_assists:
          type: number
          nullable: true
        kda:
          type: number
        kp:
          type: number
          description: Kill participation rate
        game_impact:
          type: number
        avg_net_worth:
          type: number
        avg_gpm:
          type: number
        avg_xpm:
          type: number
        avg_damage:
          type: number
        avg_last_hits:
          type: number
        avg_denies:
          type: number
        avg_heal:
          type: number
    DotaItem:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    DotaMatch:
      type: object
      properties:
        id:
          type: integer
        slug:
          type: string
          nullable: true
        tournament:
          $ref: "#/components/schemas/DotaTournament"
        stage:
          type: string
          nullable: true
        team1:
          $ref: "#/components/schemas/DotaTeamSlim"
          nullable: true
        team2:
          $ref: "#/components/schemas/DotaTeamSlim"
          nullable: true
        winner:
          $ref: "#/components/schemas/DotaTeamSlim"
          nullable: true
        team1_score:
          type: integer
          nullable: true
        team2_score:
          type: integer
          nullable: true
        bo_type:
          type: integer
          nullable: true
          description: Best of type (1, 3, 5)
        status:
          type: string
          nullable: true
        start_date:
          type: string
          format: date-time
          nullable: true
        end_date:
          type: string
          format: date-time
          nullable: true
    DotaMatchMap:
      type: object
      properties:
        id:
          type: integer
        match_id:
          type: integer
        game_number:
          type: integer
          nullable: true
        winner:
          $ref: "#/components/schemas/DotaTeamSlim"
          nullable: true
        loser:
          $ref: "#/components/schemas/DotaTeamSlim"
          nullable: true
        duration:
          type: integer
          nullable: true
        status:
          type: string
          nullable: true
        begin_at:
          type: string
          format: date-time
          nullable: true
        end_at:
          type: string
          format: date-time
          nullable: true
    DotaPlayer:
      type: object
      properties:
        id:
          type: integer
        nickname:
          type: string
        slug:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        birthday:
          type: string
          format: date
          nullable: true
        country_name:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        is_coach:
          type: boolean
        total_prize:
          type: number
          nullable: true
        team:
          $ref: "#/components/schemas/DotaTeamSlim"
          nullable: true
    DotaPlayerMatchMapStat:
      type: object
      properties:
        id:
          type: integer
        match_map_id:
          type: integer
        player:
          $ref: "#/components/schemas/DotaPlayerSlim"
        team:
          $ref: "#/components/schemas/DotaTeamSlim"
        hero:
          $ref: "#/components/schemas/DotaHero"
        role:
          type: integer
          nullable: true
        side:
          type: integer
        kills:
          type: integer
        deaths:
          type: integer
        assists:
          type: integer
        hero_level:
          type: integer
        net_worth:
          type: integer
        gold_per_min:
          type: integer
        xp_per_min:
          type: integer
        hero_damage:
          type: integer
        tower_damage:
          type: integer
        last_hits:
          type: integer
        denies:
          type: integer
        heal:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/DotaItem"
        abilities:
          type: array
          items:
            type: object
            properties:
              ability:
                $ref: "#/components/schemas/DotaAbility"
              level:
                type: integer
    DotaPlayerOverallStat:
      type: object
      properties:
        id:
          type: integer
        player:
          $ref: "#/components/schemas/DotaPlayerSlim"
        maps_played:
          type: integer
        total_kills:
          type: integer
        avg_kills:
          type: number
        total_deaths:
          type: integer
        avg_deaths:
          type: number
        total_assists:
          type: integer
        avg_assists:
          type: number
        kda:
          type: number
        kp:
          type: number
          description: Kill participation rate
        game_impact:
          type: number
        avg_net_worth:
          type: number
        avg_gpm:
          type: number
          description: Average gold per minute
        avg_xpm:
          type: number
          description: Average XP per minute
        avg_damage:
          type: number
        avg_last_hits:
          type: number
        avg_denies:
          type: number
        avg_heal:
          type: number
    DotaPlayerSlim:
      type: object
      properties:
        id:
          type: integer
        nickname:
          type: string
          nullable: true
    DotaRegion:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Region name (e.g., Europe, North America)
    DotaTeam:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
          nullable: true
        country_name:
          type: string
          nullable: true
        region:
          $ref: "#/components/schemas/DotaRegion"
          nullable: true
        rank:
          type: integer
          nullable: true
        total_money:
          type: number
          nullable: true
        tour_wins:
          type: integer
          nullable: true
    DotaTeamMatchMapStat:
      type: object
      properties:
        id:
          type: integer
        match_map_id:
          type: integer
        team:
          $ref: "#/components/schemas/DotaTeamSlim"
        enemy_team:
          $ref: "#/components/schemas/DotaTeamSlim"
        side:
          type: integer
        score:
          type: integer
        first_blood:
          type: boolean
        first_tower:
          type: boolean
        first_roshan:
          type: boolean
        roshan_kills:
          type: integer
        drafts:
          type: array
          items:
            type: object
            properties:
              hero:
                $ref: "#/components/schemas/DotaHero"
              choice_type:
                type: integer
                description: 0 for ban, 1 for pick
              order_number:
                type: integer
    DotaTeamSlim:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    DotaTournament:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
          nullable: true
        start_date:
          type: string
          format: date-time
          nullable: true
        end_date:
          type: string
          format: date-time
          nullable: true
        prize:
          type: number
          nullable: true
        players_prize:
          type: number
          nullable: true
        teams_prize:
          type: number
          nullable: true
        event_type:
          type: string
          nullable: true
          description: Event type (lan, online)
        tier:
          type: string
          nullable: true
          description: Tournament tier (s, a, b, c)
        status:
          type: string
          nullable: true
    DotaTournamentRoster:
      type: object
      properties:
        tournament_id:
          type: integer
        team_id:
          type: integer
        player:
          $ref: "#/components/schemas/DotaPlayerSlim"
    DotaTournamentTeam:
      type: object
      properties:
        tournament_id:
          type: integer
        team:
          $ref: "#/components/schemas/DotaTeamSlim"
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
    Pagination:
      type: object
      properties:
        next_cursor:
          type: integer
          description: Cursor for the next page of results
        prev_cursor:
          type: integer
          nullable: true
          description: Cursor for the previous page of results
        per_page:
          type: integer
          description: Number of results per page
    PlayerPropMeta:
      type: object
      description: Metadata for player prop responses (no pagination - all results returned in single response)
      properties:
        per_page:
          type: integer
          description: Total number of results returned
  parameters:
    CursorParam:
      name: cursor
      in: query
      required: false
      schema:
        type: integer
      description: The cursor for pagination
    PerPageParam:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        maximum: 100
        default: 25
      description: Number of results per page
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequestError:
      description: Bad Request - Invalid parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    RateLimitError:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
security:
  - ApiKeyAuth: []
paths:
  /dota/v1/teams:
    get:
      summary: Get all Dota 2 teams
      description: Retrieve a list of all professional Dota 2 teams
      tags:
        - Dota
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search teams by name
      responses:
        "200":
          description: List of Dota 2 teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaTeam"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/players:
    get:
      summary: Get all Dota 2 players
      description: Retrieve a list of all professional Dota 2 players
      tags:
        - Dota
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search players by nickname or name
        - name: team_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by team ID
      responses:
        "200":
          description: List of Dota 2 players
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaPlayer"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/heroes:
    get:
      summary: Get all Dota 2 heroes
      description: Retrieve a list of all Dota 2 heroes
      tags:
        - Dota
      responses:
        "200":
          description: List of Dota 2 heroes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaHero"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/items:
    get:
      summary: Get all Dota 2 items
      description: Retrieve a list of all Dota 2 in-game items
      tags:
        - Dota
      responses:
        "200":
          description: List of Dota 2 items
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaItem"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/abilities:
    get:
      summary: Get all Dota 2 abilities
      description: Retrieve a list of all Dota 2 hero abilities
      tags:
        - Dota
      responses:
        "200":
          description: List of Dota 2 abilities
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaAbility"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/tournaments:
    get:
      summary: Get Dota 2 tournaments
      description: Retrieve a list of professional Dota 2 tournaments. Requires ALL-STAR tier or higher.
      tags:
        - Dota
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: List of Dota 2 tournaments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaTournament"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/tournament_teams:
    get:
      summary: Get teams in a tournament
      description: Retrieve teams participating in a specific Dota 2 tournament. Requires ALL-STAR tier or higher.
      tags:
        - Dota
      parameters:
        - name: tournament_id
          in: query
          required: true
          schema:
            type: integer
          description: Tournament ID
      responses:
        "200":
          description: List of teams in tournament
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaTournamentTeam"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/tournament_roster:
    get:
      summary: Get tournament roster
      description: Retrieve player rosters for a Dota 2 tournament and team. Requires ALL-STAR tier or higher.
      tags:
        - Dota
      parameters:
        - name: tournament_id
          in: query
          required: true
          schema:
            type: integer
          description: Tournament ID
        - name: team_id
          in: query
          required: true
          schema:
            type: integer
          description: Team ID
      responses:
        "200":
          description: Tournament roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaTournamentRoster"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/hero_stats:
    get:
      summary: Get hero statistics
      description: Retrieve aggregate statistics for Dota 2 heroes across professional matches. Requires ALL-STAR tier or higher.
      tags:
        - Dota
      responses:
        "200":
          description: Hero statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaHeroStats"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/matches:
    get:
      summary: Get Dota 2 matches
      description: Retrieve professional Dota 2 matches. Requires GOAT tier.
      tags:
        - Dota
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: tournament_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by tournament ID
        - name: team_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by team ID
      responses:
        "200":
          description: List of Dota 2 matches
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaMatch"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/match_maps:
    get:
      summary: Get match maps (games)
      description: Retrieve individual games within a Dota 2 match. Requires GOAT tier.
      tags:
        - Dota
      parameters:
        - name: match_id
          in: query
          required: true
          schema:
            type: integer
          description: Match ID to get games for
      responses:
        "200":
          description: List of match maps
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaMatchMap"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/player_match_map_stats:
    get:
      summary: Get player match map statistics
      description: Retrieve detailed player statistics for individual Dota 2 games. Requires GOAT tier.
      tags:
        - Dota
      parameters:
        - name: match_map_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by match map ID
        - name: player_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by player ID
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Player match map statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaPlayerMatchMapStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/team_match_map_stats:
    get:
      summary: Get team match map statistics
      description: Retrieve detailed team statistics for individual Dota 2 games. Requires GOAT tier.
      tags:
        - Dota
      parameters:
        - name: match_map_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by match map ID
        - name: team_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by team ID
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Team match map statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaTeamMatchMapStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /dota/v1/player_overall_stats:
    get:
      summary: Get player overall statistics
      description: Retrieve career statistics for Dota 2 players. Requires GOAT tier.
      tags:
        - Dota
      parameters:
        - name: player_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by player ID
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Player overall statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/DotaPlayerOverallStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"