List All Races #

Retrieves a list of races. Requires a valid session token and the permissions.races.list permission.

Endpoint #

GET https://api.tracx.events/v1/connect/races

Headers #

{
  "Accept": "application/json",
  "Authorization": "<connect-token>"
}

Query Parameters #

Parameter	Type	Required	Description
event_id	int	No	If provided, only races belonging to the given event are returned. The filter is intersected with the token’s per-event permissions; values outside that scope yield `[]`.

Example cURL Request #

curl --request GET \
  --url https://api.tracx.events/v1/connect/races \
  --header 'Accept: application/json' \
  --header 'Authorization: <connect-token>'

Example cURL Request — filtered by event #

curl --request GET \
  --url 'https://api.tracx.events/v1/connect/races?event_id=1' \
  --header 'Accept: application/json' \
  --header 'Authorization: <connect-token>'

Sample Response #

{
    "data": {
        "items": [
            {
                "id": 1,
                "event_id": 1,
                "name": "Race name 1",
                "created_at": "2025-02-25 09:45:32",
                "updated_at": "2025-02-25 09:45:32"
            },
            {
                "id": 2,
                "event_id": 1,
                "name": "Race name 2",
                "created_at": "2025-02-25 10:59:46",
                "updated_at": "2025-02-25 11:25:52"
            }
        ]
    }
}

Response Fields #

Field	Type	Description
data.items	array	List of all races
id	int	Unique identifier of the race
event_id	int	Identifier of the event this race belongs to
name	string	Name of the race
created_at	string	Timestamp when the race was created (YYYY-MM-DD HH:MM:SS)
updated_at	string	Timestamp when the race was last updated (YYYY-MM-DD HH:MM:SS)

Error Handling #

Status Code	Meaning
200 OK	Request was successful
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Session Token does not have the required permission
422 Unprocessable Entity	The `event_id` query parameter is not a valid integer (>= 1)

Notes #

The request must include a valid session token.
The session token must have the permissions.races.list permission.
The response contains an array of race objects.
The optional event_id query parameter narrows the result to a single event. If the token only has per-event list permissions and the requested event is not in that scope, an empty list is returned.