@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api The Blue Alliance API v3
@base https://www.thebluealliance.com/api/v3
@version 3.12.1
@auth ApiKey X-TBA-Auth-Key in header
@common_fields {If-None-Match: str}
@endpoints 80
@hint download_for_search
@toc district(12), districts(1), event(21), events(3), insights(2), match(4), regional_advancement(2), search_index(1), status(1), team(27), teams(6)

@group district
@endpoint GET /district/{district_abbreviation}/dcmp_history
@required {district_abbreviation: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_abbreviation}/history
@required {district_abbreviation: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_abbreviation}/insights
@required {district_abbreviation: str}
@returns(200) {district_data: map{region_data: any, district_wide_data: any}, team_data: any}
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/advancement
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/awards
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/events
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/events/keys
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/events/simple
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/rankings
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/teams
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/teams/keys
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /district/{district_key}/teams/simple
@required {district_key: str}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group districts
@endpoint GET /districts/{year}
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group event
@endpoint GET /event/{event_key}
@required {event_key: str}
@returns(200) {key: str, name: str, event_code: str, event_type: int, district: any, city: str?, state_prov: str?, country: str?, start_date: str(date), end_date: str(date), year: int, short_name: str?, event_type_string: str, week: int?, address: str?, postal_code: str?, gmaps_place_id: str?, gmaps_url: str(url)?, lat: num(double)?, lng: num(double)?, location_name: str?, timezone: str?, website: str?, first_event_id: str?, first_event_code: str?, webcasts: [map], division_keys: [str], parent_event_key: str?, playoff_type: int?, playoff_type_string: str?, remap_teams: map?}
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/advancement_points
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/alliances
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/awards
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/coprs
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/district_points
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/insights
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/matches
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/matches/keys
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/matches/simple
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/matches/timeseries
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/oprs
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/predictions
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/rankings
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/regional_champs_pool_points
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/simple
@required {event_key: str}
@returns(200) {key: str, name: str, event_code: str, event_type: int, district: any, city: str?, state_prov: str?, country: str?, start_date: str(date), end_date: str(date), year: int}
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/team_media
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/teams
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/teams/keys
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/teams/simple
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /event/{event_key}/teams/statuses
@required {event_key: str}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group events
@endpoint GET /events/{year}
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /events/{year}/keys
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /events/{year}/simple
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group insights
@endpoint GET /insights/leaderboards/{year}
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /insights/notables/{year}
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group match
@endpoint GET /match/{match_key}
@required {match_key: str}
@returns(200) {key: str, comp_level: str, set_number: int, match_number: int, alliances: map{red: map{score: int, team_keys: [str], surrogate_team_keys: [str], dq_team_keys: [str]}, blue: map{score: int, team_keys: [str], surrogate_team_keys: [str], dq_team_keys: [str]}}, winning_alliance: str, event_key: str, time: int(int64)?, actual_time: int(int64)?, predicted_time: int(int64)?, post_result_time: int(int64)?, score_breakdown: any, videos: [map]}
@errors {304, 401, 404}

@endpoint GET /match/{match_key}/simple
@required {match_key: str}
@returns(200) {key: str, comp_level: str, set_number: int, match_number: int, alliances: map{red: map{score: int, team_keys: [str], surrogate_team_keys: [str], dq_team_keys: [str]}, blue: map{score: int, team_keys: [str], surrogate_team_keys: [str], dq_team_keys: [str]}}, winning_alliance: str, event_key: str, time: int(int64)?, predicted_time: int(int64)?, actual_time: int(int64)?}
@errors {304, 401, 404}

@endpoint GET /match/{match_key}/timeseries
@required {match_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /match/{match_key}/zebra_motionworks
@required {match_key: str}
@returns(200) {key: str, times: [num(double)], alliances: map{red: [map], blue: [map]}}
@errors {304, 401, 404}

@endgroup

@group regional_advancement
@endpoint GET /regional_advancement/{year}
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /regional_advancement/{year}/rankings
@required {year: int}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group search_index
@endpoint GET /search_index
@returns(200) {teams: [map], events: [map]}
@errors {304, 401, 404}

@endgroup

@group status
@endpoint GET /status
@returns(200) {current_season: int, max_season: int, is_datafeed_down: bool, down_events: [str], ios: map{min_app_version: int, latest_app_version: int}, android: map{min_app_version: int, latest_app_version: int}, max_team_page: int}
@errors {304, 401, 404}

@endgroup

@group team
@endpoint GET /team/{team_key}
@required {team_key: str}
@returns(200) {key: str, team_number: int, nickname: str, name: str, school_name: str?, city: str?, state_prov: str?, country: str?, address: str?, postal_code: str?, gmaps_place_id: str?, gmaps_url: str(url)?, lat: num(double)?, lng: num(double)?, location_name: str?, website: str(url)?, rookie_year: int?, motto: str?}
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/awards
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/awards/{year}
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/districts
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/event/{event_key}/awards
@required {team_key: str, event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/event/{event_key}/matches
@required {team_key: str, event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/event/{event_key}/matches/keys
@required {team_key: str, event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/event/{event_key}/matches/simple
@required {team_key: str, event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/event/{event_key}/status
@required {team_key: str, event_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events/keys
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events/simple
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events/{year}
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events/{year}/keys
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events/{year}/simple
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/events/{year}/statuses
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/history
@required {team_key: str}
@returns(200) {events: [map], awards: [map]}
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/matches/{year}
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/matches/{year}/keys
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/matches/{year}/simple
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/media/tag/{media_tag}
@required {team_key: str, media_tag: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/media/tag/{media_tag}/{year}
@required {team_key: str, media_tag: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/media/{year}
@required {team_key: str, year: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/robots
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/simple
@required {team_key: str}
@returns(200) {key: str, team_number: int, nickname: str, name: str, city: str?, state_prov: str?, country: str?}
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/social_media
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /team/{team_key}/years_participated
@required {team_key: str}
@returns(200)
@errors {304, 401, 404}

@endgroup

@group teams
@endpoint GET /teams/{page_num}
@required {page_num: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /teams/{page_num}/keys
@required {page_num: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /teams/{page_num}/simple
@required {page_num: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /teams/{year}/{page_num}
@required {year: int, page_num: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /teams/{year}/{page_num}/keys
@required {year: int, page_num: int}
@returns(200)
@errors {304, 401, 404}

@endpoint GET /teams/{year}/{page_num}/simple
@required {year: int, page_num: int}
@returns(200)
@errors {304, 401, 404}

@endgroup

@end