logo
API docs by Redocly

Nexus API (v1.2.0)

Download OpenAPI specification:

Get live event data with accurate match timing estimates. Visit frc.nexus/api to get your API key or to register your webhook URLs.

Availability
Live event status is only available for events that are using Nexus to manage queuing. Match status and times will not be accurate for events not using Nexus for queuing.

Timestamps
All timestamps are represented using Unix time in milliseconds. Most timestamps are computed dynamically and could change every time you receive a new status.

Attribution
Include a link back to frc.nexus in any projects in which you utilize Nexus data.

Live event status (push) Webhook

header Parameters
Nexus-Token
string

The token from frc.nexus/api that can be used to verify that Nexus is the caller of your webhook.

Request Body schema: application/json

Register your webhook at frc.nexus/api.

A POST request is made to each webhook when any of the following happens:

  • a match status is updated
  • a break time is updated
  • a team is added to a playoff alliance
  • an announcement is posted or removed
  • a parts request is posted or removed

Note that some of these events frequently happen multiple times within a short period of time. Build your application to handle repeated requests and ensure you always use the data with the most recent dataAsOfTime.

eventKey
string (EventKey)

The unique identifier of the event. For official events, the event key will match the event code as displayed on frc.events. Offseason events may use event keys derived from either frc.events or thebluealliance.com, or will be arbitrary. Examples: 2024casf, demo1234

dataAsOfTime
number

The timestamp (Unix time in milliseconds) at which this event status snapshot was generated by Nexus.

nowQueuing
string or null

The human-friendly label for the latest match that is queuing. Null if the event is not currently queuing a match. Examples: Practice 1, Qualification 24, Qualification 24 Replay, Playoff 8, Final 1

Array of objects (Match)

All scheduled matches for this event, sorted by play order (practice matches first, then qualifications, then playoffs). This array is empty if the event has not yet scheduled any matches. This array can include scheduled match replays which are indicated by the replayOf property.

Array of objects (Announcement)

Current announcements that are posted for this event. This array is empty if there are no current announcements.

Array of objects (PartsRequest)

Current parts requests that are posted for this event. This array is empty if there are no current parts requests.

Responses

Request samples

Content type
application/json
Example
{
  • "eventKey": "2024casf",
  • "dataAsOfTime": 1716591216610,
  • "matches": [ ],
  • "announcements": [ ],
  • "partsRequests": [ ]
}

Match status (push) Webhook

header Parameters
Nexus-Token
string

The token from frc.nexus/api that can be used to verify that Nexus is the caller of your webhook.

Request Body schema: application/json

Register your webhook for a specific team number at frc.nexus/api.

A POST request is made to each webhook when the match status is updated for a match which includes the specified team number. Multiple status updates could happen quickly so ensure you always use the data with the most recent dataAsOfTime.

eventKey
string (EventKey)

The unique identifier of the event. For official events, the event key will match the event code as displayed on frc.events. Offseason events may use event keys derived from either frc.events or thebluealliance.com, or will be arbitrary. Examples: 2024casf, demo1234

dataAsOfTime
number

The timestamp (Unix time in milliseconds) at which this event status snapshot was generated by Nexus.

object (Match)

The updated match.

Responses

Request samples

Content type
application/json
Example
{
  • "eventKey": "2024casf",
  • "dataAsOfTime": 1716591216610,
  • "match": {
    • "label": "Practice 4",
    • "status": "Now queuing",
    • "redTeams": [
      ],
    • "blueTeams": [
      ],
    • "times": {
      }
    }
}

Live event status (pull)

Authorizations:
Nexus-Api-Key
path Parameters
eventKey
required
string (EventKey)
Examples:
  • 2024casf - The year & event code of a real event. Get event codes from frc.events or thebluealliance.com.
  • demo1234 - Your demo event key for testing. Get your demo event key from frc.nexus/api.

The event you want to fetch the status of.

Responses

Response Schema: application/json
eventKey
string (EventKey)

The unique identifier of the event. For official events, the event key will match the event code as displayed on frc.events. Offseason events may use event keys derived from either frc.events or thebluealliance.com, or will be arbitrary. Examples: 2024casf, demo1234

dataAsOfTime
number

The timestamp (Unix time in milliseconds) at which this event status snapshot was generated by Nexus.

nowQueuing
string or null

The human-friendly label for the latest match that is queuing. Null if the event is not currently queuing a match. Examples: Practice 1, Qualification 24, Qualification 24 Replay, Playoff 8, Final 1

Array of objects (Match)

All scheduled matches for this event, sorted by play order (practice matches first, then qualifications, then playoffs). This array is empty if the event has not yet scheduled any matches. This array can include scheduled match replays which are indicated by the replayOf property.

Array of objects (Announcement)

Current announcements that are posted for this event. This array is empty if there are no current announcements.

Array of objects (PartsRequest)

Current parts requests that are posted for this event. This array is empty if there are no current parts requests.

Request samples 

curl -i -X GET \
  "https://frc.nexus/api/v1/event/{eventKey}" \
  --header "Nexus-Api-Key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
Example
{
  • "eventKey": "2024casf",
  • "dataAsOfTime": 1716591216610,
  • "matches": [ ],
  • "announcements": [ ],
  • "partsRequests": [ ]
}

Pit addresses (pull)

Authorizations:
Nexus-Api-Key
path Parameters
eventKey
required
string (EventKey)
Examples:
  • 2024casf - The year & event code of a real event. Get event codes from frc.events or thebluealliance.com.
  • demo1234 - Your demo event key for testing. Get your demo event key from frc.nexus/api.

The event you want to fetch the pits for.

Responses

Response Schema: application/json
teamNumber*
additional property
string (PitAddress)

A pit address is an arbitrary string usually in the form of letter + number. They are sometimes useful for finding where a team's pit is located within a venue. Examples: A1, C12

Response samples

Content type
application/json
Example
{
  • "100": "A1",
  • "200": "A2",
  • "300": "B1",
  • "400": "B2"
}