Nexus API

https://frc.nexus/api/v1/docs
Admin
The Nexus API provides real-time event status, match timing estimates, and queuing information for...
Tokens:1,844
Snippets:10
Trust Score:5.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get Live Event Status: cURL Request Example

Source: https://frc.nexus/api/v1/docs/index

A cURL command example demonstrating how to make a `GET` request to the `/event/{eventKey}` endpoint. This snippet shows how to include the `Nexus-Api-Key` in the request header to retrieve live event status.

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

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

### Match Data API Response Sample (200 OK)

Source: https://frc.nexus/api/v1/docs/index

Example JSON structure for a successful response from a match data endpoint, showing event key, data timestamp, and empty arrays for matches, announcements, and parts requests.

```JSON
{
  "eventKey": "2024casf",
  "dataAsOfTime": 1716591216610,
  "matches": [],
  "announcements": [],
  "partsRequests": []
}
```

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

### GET /event/{eventKey} API Endpoint Definition

Source: https://frc.nexus/api/v1/docs/index

Documents the `GET /event/{eventKey}` endpoint for retrieving live event status. It specifies the URL structure, required `Nexus-Api-Key` authorization, path parameters, and possible HTTP responses with their meanings.

```APIDOC
Endpoint: GET /event/{eventKey}
URL: https://frc.nexus/api/v1/event/{eventKey}
Authorizations:
  Nexus-Api-Key
Path Parameters:
  eventKey: string (EventKey) required - The event to fetch status of. Examples: `2024casf`, `demo1234`
Responses:
  200: Live event status
  401: Missing API key.
  403: Invalid API key.
  404: `eventKey` does not exist.
  500: An unknown server error occured.
```

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

### Webhook POST Request Sample Payload (JSON)

Source: https://frc.nexus/api/v1/docs/index

An example JSON payload demonstrating the structure of data received by a webhook. This sample illustrates a match status update, including event details, team lists, and estimated match times.

```json
{
  "eventKey": "2024casf",
  "dataAsOfTime": 1716591216610,
  "match": {
    "label": "Practice 4",
    "status": "Now queuing",
    "redTeams": [
      "1800",
      "600",
      "3100"
    ],
    "blueTeams": [
      "200",
      "300",
      "2000"
    ],
    "times": {
      "estimatedQueueTime": 1716591742580,
      "estimatedOnDeckTime": 1716592342045,
      "estimatedOnFieldTime": 1716592942045,
      "estimatedStartTime": 1716593362045,
      "actualQueueTime": 1716591742580
    }
  }
}
```

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

### Pit Addresses API Response Sample (200 OK)

Source: https://frc.nexus/api/v1/docs/index

Example JSON structure for a successful response from the pit addresses endpoint, mapping team numbers to their respective pit locations.

```JSON
{
  "100": "A1",
  "200": "A2",
  "300": "B1",
  "400": "B2"
}
```

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

### GET /event/{eventKey} Response Schema (application/json)

Source: https://frc.nexus/api/v1/docs/index

Defines the JSON schema for the successful response (200 OK) from the `GET /event/{eventKey}` endpoint. It outlines the structure of the live event status data, including event key, timestamp, current queuing status, and arrays for matches, announcements, and parts requests.

```APIDOC
eventKey: string (EventKey)
dataAsOfTime: number
nowQueuing: string or null
matches: Array of objects (Match)
announcements: Array of objects (Announcement)
partsRequests: Array of objects (PartsRequest)
```

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

### GET /event/{eventKey}/pits API Endpoint Documentation

Source: https://frc.nexus/api/v1/docs/index

Detailed documentation for the API endpoint to retrieve pit addresses for a given FRC event, including authorization, path parameters, and various response codes.

```APIDOC
Method: GET
Path: /event/{eventKey}/pits
Full URL: https://frc.nexus/api/v1/event/{eventKey}/pits

Authorizations:
  - Nexus-Api-Key

Path Parameters:
  - eventKey (required): string (EventKey)
    Description: The event you want to fetch the pits for.
    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.

Responses:
  - 200 OK:
    Description: Team number to pit address map
    Content-Type: application/json
    Schema Properties:
      - teamNumber* (additional property): string (PitAddress)
        Description: 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
  - 401 Unauthorized:
    Description: Missing API key. Get your API key from frc.nexus/api and include it in the `Nexus-Api-Key` header.
  - 403 Forbidden:
    Description: Invalid API key. Ensure the key you're using matches your key at frc.nexus/api. If abuse was detected, your API key may have been disabled. Email contact@frc.nexus for support.
  - 404 Not Found:
    Description: `eventKey` does not exist.
  - 500 Internal Server Error:
    Description: An unknown server error occurred. Try again later or email contact@frc.nexus for support.
```

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

### Match Status Push Webhook API Documentation

Source: https://frc.nexus/api/v1/docs/index

This section describes the webhook for receiving match status updates. It specifies the required header parameters for authentication and verification of the caller.

```APIDOC
Header Parameters:
  Nexus-Token: string
    description: The token from frc.nexus/api that can be used to verify that Nexus is the caller of your webhook.
```

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

### Live Event Status Push Webhook API Documentation

Source: https://frc.nexus/api/v1/docs/index

This section details the webhook for receiving live event status updates via a POST request. It outlines the required header parameters, the structure of the request body schema (application/json), and expected response codes. The webhook is triggered by various event updates, and applications should be built to handle frequent requests and use the most recent 'dataAsOfTime'.

```APIDOC
Header Parameters:
  Nexus-Token: string
    description: The token from frc.nexus/api that can be used to verify that Nexus is the caller of your webhook.
```

```APIDOC
Request Body Schema: application/json
  eventKey: string (EventKey)
    description: 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
    description: The timestamp (Unix time in milliseconds) at which this event status snapshot was generated by Nexus.
  nowQueuing: string or null
    description: 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
  matches: Array of objects (Match)
    description: 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.
  announcements: Array of objects (Announcement)
    description: Current announcements that are posted for this event. This array is empty if there are no current announcements.
  partsRequests: Array of objects (PartsRequest)
    description: Current parts requests that are posted for this event. This array is empty if there are no current parts requests.
```

```APIDOC
Responses:
  200:
    description: Return a 200 status to indicate that the data was received successfully.
  default:
    description: All other response codes are considered errors and do not result in retries. Webhooks that consistently fail to return a 200 status will be automatically disabled.
```

```JSON
{
  "eventKey": "2024casf",
  "dataAsOfTime": 1716591216610,
  "matches": [ ],
  "announcements": [ ],
  "partsRequests": [ ]
}
```

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

### Webhook POST Request Body Schema

Source: https://frc.nexus/api/v1/docs/index

Defines the JSON schema for the payload sent to registered webhooks. This payload is delivered when a match status is updated for a team, containing the event key, data timestamp, and the updated match object.

```APIDOC
eventKey: string (EventKey)
dataAsOfTime: number
match: object (Match)
```
Tokens:
Raw