The Blue Alliance Developer APIs

https://www.thebluealliance.com/apidocs
Admin
The Blue Alliance Developer APIs provide programmatic access to FIRST Robotics Competition data,...
Tokens:4,458
Snippets:21
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example JSON for Ping Notification

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload for a `ping` notification, demonstrating a test message with a title and description.

```JSON
{"message_data": {"title": "Test Message", "desc": "This is a test message ensuring your device can recieve push messages from The Blue Alliance."}, "message_type": "ping"}
```

--------------------------------

### Example JSON for Broadcast Notification

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload for a `broadcast` notification, showing a test message with a title, description, and an optional URL.

```JSON
{"message_data": {"title": "Test", "desc": "Test Broadcast", "url": "http://foo.bar"}, "message_type": "broadcast"}
```

--------------------------------

### Example JSON for Event Schedule Updated Notification

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload for a `schedule_updated` notification, including event key, name, and the first match time.

```JSON
{"message_data": {"event_key": "2014necmp", "event_name": "New England FRC Region Championship", "first_match_time": 1397330280}, "message_type": "schedule_updated"}
```

--------------------------------

### Example JSON Payload for Upcoming Match Notification

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload demonstrating the structure and typical values for an `upcoming_match` notification, including event, match, team, time, and webcast details.

```JSON
{"message_data": {"event_key": "2014necmp", "match_key": "2014necmp_f1m1", "event_name": "New England FRC Region Championship", "team_keys": ["frc195", "frc558", "frc5122", "frc177", "frc230", "frc4055"], "scheduled_time": 1397330280, "predicted_time": 1397330280, "webcast": {"type": "twitch", "channel": "nefirst_blue"}}, "message_type": "upcoming_match"}
```

--------------------------------

### The Blue Alliance Webhook Verification Message Example

Source: https://www.thebluealliance.com/apidocs/webhooks

An example of the `verification` message type sent by The Blue Alliance to a newly configured webhook URL. This message is crucial for the initial verification process to activate the webhook.

```APIDOC
{
  "message_type": "verification",
  "message_data": {
    "verification_key": "a93774ec6197d456f4aaadfea5fdba6697e71e6a"
  }
}
```

--------------------------------

### Example Webhook Verification JSON Payload

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload demonstrating the structure of a webhook verification notification. This payload includes the `message_data` object with a sample `verification_key` and specifies the `message_type` as `verification`.

```JSON
{"message_data": {"verification_key": "8279a61abdeee0cf46a86136bf888188a4b18cdf"}, "message_type": "verification"}
```

--------------------------------

### Example JSON for Alliance Selection Notification

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload representing an `alliance_selection` notification from The Blue Alliance API. It includes detailed event information such as name, key, dates, location, and webcasts.

```JSON
{"message_data": {"event_name": "New England FRC Region Championship", "event_key": "2014necmp", "event": {"address": "Boston, MA 02215, USA", "city": "Boston", "country": "USA", "district": {"abbreviation": "ne", "display_name": "New England", "key": "2014ne", "year": 2014}, "division_keys": [], "end_date": "2014-04-12", "event_code": "necmp", "event_type": 2, "event_type_string": "District Championship", "first_event_code": "necmp", "first_event_id": "10871", "gmaps_place_id": "ChIJFzjlY_B544kRyL6j4ABuNCs", "gmaps_url": "https://maps.google.com/?cid=3113234192467738312", "key": "2014necmp", "lat": 42.3504997, "lng": -71.1053991, "location_name": "Boston University", "name": "New England FRC Region Championship", "parent_event_key": null, "playoff_type": null, "playoff_type_string": null, "postal_code": "02215", "short_name": "New England", "start_date": "2014-04-10", "state_prov": "MA", "timezone": "America/New_York", "webcasts": [{"channel": "7031031", "file": "2797186", "type": "livestream"}, {"channel": "7234441", "file": "2797207", "type": "livestream"}], "website": "http://www.nefirst.org/", "week": 6, "year": 2014}}, "message_type": "alliance_selection"}
```

--------------------------------

### Example JSON for Awards Posted Notification

Source: https://www.thebluealliance.com/apidocs/webhooks

An example JSON payload for an `awards_posted` notification, showing an event with a 'Regional Chairman's Award' and its recipients.

```JSON
{"message_data": {"event_key": "2014necmp", "event_name": "New England FRC Region Championship", "awards": [{"event_key": "2014necmp", "award_type": 0, "name": "Regional Chairman's Award", "recipient_list": [{"team_number": 2067, "awardee": null}, {"team_number": 78, "awardee": null}, {"team_number": 811, "awardee": null}, {"team_number": 2648, "awardee": null}], "year": 2014}]}, "message_type": "awards_posted"}
```

--------------------------------

### Competition Level Starting Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

This notification is sent when a new competition level (e.g., quarterfinal, semifinal) is starting, typically alongside upcoming match notifications. It provides the event key, event name, competition level, and an optional scheduled time.

```APIDOC
Message Key: starting_comp_level
message_data Fields:
  event_key: TBA API key for the Event the Match will be played at (Example: 2014necmp)
  event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship)
  comp_level: One of [these strings](https://github.com/the-blue-alliance/the-blue-alliance/blob/py3/src/backend/common/consts/comp_level.py#L6-L11) representing the competition level that is starting (Example: qf)
  scheduled_time: (Optional) Time that the first match of the comp level was originally scheduled for, in UNIX UTC. Will not be included if the match does not have a scheduled start time (Example: 1397330280)
```

```json
{"message_data": {"event_name": "New England FRC Region Championship", "comp_level": "f", "event_key": "2014necmp", "scheduled_time": 1397330280}, "message_type": "starting_comp_level"}
```

--------------------------------

### Match Score Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

This section details the structure and example JSON payload for the `match_score` notification, which provides real-time updates on match scores. It includes fields like event and match keys, team key (optional), event name, and a full Match object.

```APIDOC
Message Key: match_score
message_data Fields:
  event_key: TBA API key for the Event the Match will be played at (Example: 2014necmp)
  match_key: TBA API key for the Match (Example: 2014necmp_f1m1)
  team_key: (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. (Example: frc7332)
  event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship)
  match: A TBA API [Match](/apidocs/v3#model-Match) object for the match.
```

```json
{"message_data": {"event_name": "New England FRC Region Championship", "match": {"comp_level": "f", "match_number": 1, "videos": [], "time_string": "3:18 PM", "set_number": 1, "key": "2014necmp_f1m1", "time": 1397330280, "score_breakdown": null, "alliances": {"blue": {"score": 154, "teams": ["frc177", "frc230", "frc4055"]}, "red": {"score": 78, "teams": ["frc195", "frc558", "frc5122"]} }, "event_key": "2014necmp"} }, "message_type": "match_score"}
```

--------------------------------

### Upcoming Match Notification API Structure

Source: https://www.thebluealliance.com/apidocs/webhooks

Defines the structure of the `upcoming_match` notification, detailing the `message_data` fields, their types, and descriptions. This notification is sent before a match starts, providing details about the event, match, participating teams, and scheduled/predicted times.

```APIDOC
Notification: upcoming_match
  message_data: Object
    event_key: string - TBA API key for the Event the Match will be played at (e.g., 2014necmp)
    match_key: string - TBA API key for the Match (e.g., 2014necmp_f1m1)
    team_key: string (Optional) - TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. (e.g., frc7332)
    event_name: string - Official name of event on record either provided by *FIRST* or organizers of offseason event (e.g., New England FRC Region Championship)
    team_keys: array<string> - List of TBA API Team keys for all teams participating in the match (e.g., frc195, frc558, ...)
    scheduled_time: number (Optional) - Time that the match was originally scheduled for, in UNIX UTC. Will not be included if the match does not have a scheduled start time (e.g., 1397330280)
    predicted_time: number (Optional) - Time that the match is predicted to start at based on the times that scores were posted for previous events, in UNIX UTC. Will not be included if the match start time cannot be predicted (e.g., 1397330280)
    webcast: Webcast Object (Optional) - A TBA API Webcast object for the Event. Only one webcast will be sent, regardless of how many webcasts the Event has. Will only include webcasts that have been determined to be "online". Will not be included if there are no online webcats for the event.
      type: string
      channel: string
  message_type: string - Always "upcoming_match"
```

--------------------------------

### Match Video Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

This notification is sent every time a match video is added to a match. It includes details such as event and match keys, team key (optional), event name, and a Match object with video information.

```APIDOC
Message Key: match_video
message_data Fields:
  event_key: TBA API key for the Event the Match was played at (Example: 2014necmp)
  match_key: TBA API key for the Match (Example: 2014necmp_f1m1)
  team_key: (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. (Example: frc7332)
  event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship)
  match: A TBA API [Match](/apidocs/v3#model-Match) object for the match.
```

```json
{"message_data": {"event_name": "New England FRC Region Championship", "match": {"comp_level": "f", "match_number": 1, "videos": [{"key": "ZrDxXDC1y5I", "type": "youtube"}], "time_string": "3:18 PM", "set_number": 1, "key": "2014necmp_f1m1", "time": 1397330280, "score_breakdown": null, "event_key": "2014necmp"} }, "message_type": "match_video"}
```

--------------------------------

### Ping Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

Documentation for the `ping` notification, used to send a test message to an individual one of the user's connected devices from the Account Overview page. It defines the message key and fields for `title` and `desc`.

```APIDOC
Message Key: `ping`

`message_data` Fields
| Key | Description | Examples |
| --- | --- | --- |
| `title` |  | Test Notification |
| `desc` |  | This is a test message ensuring your device can recieve push messages from The Blue Alliance. |
```

--------------------------------

### The Blue Alliance Read API v3 Authentication

Source: https://www.thebluealliance.com/apidocs/index

Authentication for The Blue Alliance Read API v3 requires an access token, which can be generated from your Account Dashboard. This token must be included with each request by passing it in the `X-TBA-Auth-Key` header or as a URL parameter.

```APIDOC
Authentication Header:
  Name: X-TBA-Auth-Key
  Value: YOUR_ACCESS_TOKEN
  Location: Header or URL Parameter
  Note: Generate token from Account Dashboard
```

--------------------------------

### Event Schedule Updated Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

Documentation for the `schedule_updated` notification, sent when new unplayed matches are added to a live event. It specifies the message key and fields such as `event_key`, `event_name`, and an optional `first_match_time` in UNIX UTC.

```APIDOC
Message Key: `schedule_updated`

`message_data` Fields
| Key | Description | Examples |
| --- | --- | --- |
| `event_key` | TBA API key for the Event the alliance selection results were posted at | 2014necmp |
| `event_name` | Official name of event on record either provided by *FIRST* or organizers of offseason event | New England FRC Region Championship |
| `first_match_time` | **(Optional)** Time that the next unplayed match for the event is scheduled for, in UNIX UTC. Will not be included if the match does not have a scheduled start time | 1397330280 |
```

--------------------------------

### Broadcast Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

Documentation for the `broadcast` notification, which can be sent by TBA Admins when they want to announce something important. It specifies the message key and fields for `title`, `desc`, and an optional `url`.

```APIDOC
Message Key: `broadcast`

`message_data` Fields
| Key | Description | Examples |
| --- | --- | --- |
| `title` | Title of the notification to be shown | Test |
| `desc` | Contents of the notification | Test Broadcast |
| `url` | **(Optional)** A URL with additional information | http://foo.bar |
```

--------------------------------

### Webhook Verification Notification Structure (APIDOC)

Source: https://www.thebluealliance.com/apidocs/webhooks

Defines the structure of the `verification` message type for The Blue Alliance API webhooks. It specifies the message key and the fields contained within the `message_data` payload, particularly the `verification_key` which is a SHA1 hash required for webhook activation.

```APIDOC
Webhook Verification Notification:
  Message Key: verification
  message_data Fields:
    verification_key:
      Type: string (SHA1 hash)
      Description: The SHA1 verification key for the webhook
      Example: 8279a61abdeee0cf46a86136bf888188a4b18cdf
```

--------------------------------

### Alliance Selection Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

These notifications are posted after alliance selection results have been published for an event. It includes the event key, an optional team key, event name, and a full Event object.

```APIDOC
Message Key: alliance_selection
message_data Fields:
  event_key: TBA API key for the Event the alliance selection results were posted at (Example: 2014necmp)
  team_key: (Optional) TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. (Example: frc7332)
  event_name: Official name of event on record either provided by *FIRST* or organizers of offseason event (Example: New England FRC Region Championship)
  event: A TBA API [Event](/apidocs/v3#model-Event) object for the event.
```

--------------------------------

### The Blue Alliance Read API v3 Base URL

Source: https://www.thebluealliance.com/apidocs/index

All requests to The Blue Alliance Read API v3 should be made to this base URL. This is the primary endpoint for accessing data such as event listings, team information, and match results.

```APIDOC
Base URL: https://www.thebluealliance.com/api/v3
```

--------------------------------

### Awards Posted Notification API Documentation

Source: https://www.thebluealliance.com/apidocs/webhooks

Documentation for the `awards_posted` notification, sent every time an award is added at a live event. It details the message key, required fields like `event_key`, `event_name`, and a list of `Award` objects, with an optional `team_key`.

```APIDOC
Message Key: `awards_posted`

`message_data` Fields
| Key | Description | Examples |
| --- | --- | --- |
| `event_key` | TBA API key for the Event the alliance selection results were posted at | 2014necmp |
| `team_key` | **(Optional)** TBA API key for the Team. Will only be included if the upcoming match notification is being sent for a Team subscription. | frc7332 |
| `event_name` | Official name of event on record either provided by *FIRST* or organizers of offseason event | New England FRC Region Championship |
| `awards` | A list of TBA API [Award](/apidocs/v3#model-Award) objects that are being awarded. In the case of an Event subscription, all awards for the event will be sent. In the case of a Team subscription, only awards won by the team will be sent. |  |
```

--------------------------------

### The Blue Alliance Webhook Request Structure and Validation

Source: https://www.thebluealliance.com/apidocs/webhooks

Details the common structure of all webhook POST requests from The Blue Alliance, including the required JSON payload fields `message_type` and `message_data`, and the `X-TBA-HMAC` header used for validating the request's authenticity via HMAC-SHA256.

```APIDOC
Webhook Request:
  Method: POST
  Content-Type: application/json
  Timeout: 10s (from TBA servers)

  Headers:
    X-TBA-HMAC: string
      Description: HMAC-SHA256 hash of (secret_key + payload_string)
      Purpose: Client-side request validation

  Body (JSON Payload):
    message_type: string
      Description: Identifies the type of event being pushed (e.g., "verification", "upcoming_match").
    message_data: object
      Description: Contains data specific to the 'message_type'.
```
Tokens:
Raw