Races API — Create and Manage Race Events

The Races API lets you manage the race catalog within Astral. Races serve as goal events that athletes can target in their training. You can create race entries, filter the catalog by type and date, and search by name or location. All authenticated endpoints require a valid Bearer token.

List races

GET /api/v1/races

Returns races from the catalog. Supports filtering by type, subtype, location, and date range, as well as a convenience upcoming flag and full-text search.

Query parameters

race_type

string

Filter by race type. One of: run, bike, swim, triathlon, walk, hike.

race_subtype

string

Filter by race subtype, e.g. marathon, 5k, sprint-triathlon.

location

string

Filter by location using a partial case-insensitive match.

date_from

string

Return only races on or after this ISO 8601 datetime. Example: 2025-06-01T00:00:00Z.

date_to

string

Return only races on or before this ISO 8601 datetime.

upcoming

boolean

Set to true to return only future races. Defaults to returning 10 results; combine with limit to adjust.

string

Search by race name or location. Returns up to 20 results by default.

limit

integer

Maximum number of races to return. Defaults to 50.

Example request

curl https://app.nexrex.ai/api/v1/races \
  -H "Authorization: Bearer <token>" \
  -G \
  --data-urlencode "race_type=run" \
  --data-urlencode "upcoming=true" \
  --data-urlencode "limit=10"

Response

status

string

ok on success.

data

array

List of race objects.

metadata

object

Response metadata.

metadata.total

integer

Total number of races returned.

metadata.filters

object

Echo of the applied query parameters.

Create a race

POST /api/v1/races

Adds a new race to the catalog.

Request body

race_name

string

required

Name of the race.

race_type

string

required

Type of the race. Must be one of: run, bike, swim, triathlon, walk, hike.

race_subtype

string

required

Subtype of the race, e.g. marathon, half-marathon, 5k, sprint-triathlon.

race_date

string

required

Race date in ISO 8601 format. Example: 2025-10-05T08:00:00Z.

race_location

string

required

Location of the race, e.g. Chicago, IL, USA.

race_description

string

Freeform description of the race event.

race_website_url

string

URL to the official race website.

race_image_url

string

URL to a cover image for the race.

race_timezone

string

IANA timezone for the race, e.g. America/Chicago.

race_participant_count

integer

Expected or historical participant count. Must be a non-negative integer.

race_variants

array

List of distance or format variants offered, e.g. ["5K", "10K", "Half Marathon"].

race_categories

array

List of participant categories, e.g. ["Open", "Masters", "Junior"].

Example request

curl -X POST https://app.nexrex.ai/api/v1/races \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "race_name": "Chicago Marathon",
    "race_type": "run",
    "race_subtype": "marathon",
    "race_date": "2025-10-05T08:00:00Z",
    "race_location": "Chicago, IL, USA",
    "race_description": "One of the six World Marathon Majors.",
    "race_website_url": "https://www.chicagomarathon.com",
    "race_timezone": "America/Chicago",
    "race_variants": ["Marathon"],
    "race_categories": ["Open", "Masters", "Wheelchair"]
  }'

Response

Returns 201 Created.

status

string

ok on success.

race_id

string

Unique identifier of the created race.

message

string

Race created successfully.

data

object

The created race object.

Get a race

GET /api/v1/races/{race_id}

Returns full details for a single race, including the real-time participant count.

Path parameters

race_id

string

required

The unique identifier of the race to retrieve.

Example request

curl https://app.nexrex.ai/api/v1/races/race_xyz456 \
  -H "Authorization: Bearer <token>"

Response

status

string

ok on success.

data

object

Full race object.

data.race_name

string

Name of the race.

data.race_type

string

Type of the race.

data.race_subtype

string

Subtype of the race.

data.race_date

string

Race date in ISO 8601 format.

data.race_location

string

Location of the race.

data.race_description

string

Description of the race.

data.race_website_url

string

URL to the official race website.

data.race_image_url

string

URL to the race’s cover image.

data.race_timezone

string

IANA timezone string.

data.race_participant_count

integer

Expected participant count.

data.participants_count

integer

Real-time registered participants count from the leaderboard.

data.race_variants

array

List of distance or format variants.

data.race_categories

array

List of participant categories.

Update a race

PUT /api/v1/races/{race_id}

Updates an existing race. Only the fields provided in the request body are changed.

Path parameters

race_id

string

required

The unique identifier of the race to update.

Request body

All fields are optional. Supply only the fields you want to change. The same validation rules apply as for race creation.

race_name

string

Updated race name.

race_type

string

Updated race type. Must be one of: run, bike, swim, triathlon, walk, hike.

race_subtype

string

Updated race subtype.

race_date

string

Updated race date in ISO 8601 format.

race_location

string

Updated race location.

race_description

string

Updated description.

race_website_url

string

Updated website URL.

race_image_url

string

Updated cover image URL.

race_timezone

string

Updated IANA timezone string.

race_participant_count

integer

Updated participant count. Must be a non-negative integer.

race_variants

array

Updated list of race variants.

race_categories

array

Updated list of participant categories.

Example request

curl -X PUT https://app.nexrex.ai/api/v1/races/race_xyz456 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "race_participant_count": 45000,
    "race_website_url": "https://www.chicagomarathon.com/2025"
  }'

Response

status

string

ok on success.

message

string

Race updated successfully.

data

object

The updated race object.

Delete a race

DELETE /api/v1/races/{race_id}

Permanently removes a race from the catalog.

Path parameters

race_id

string

required

The unique identifier of the race to delete.

Example request

curl -X DELETE https://app.nexrex.ai/api/v1/races/race_xyz456 \
  -H "Authorization: Bearer <token>"

Response

status

string

ok on success.

message

string

Race deleted successfully.

​List races

​Query parameters

​Example request

​Response

​Create a race

​Request body

​Example request

​Response

​Get a race

​Path parameters

​Example request

​Response

​Update a race

​Path parameters

​Request body

​Example request

​Response

​Delete a race

​Path parameters

​Example request

​Response

List races

Query parameters

Example request

Response

Create a race

Request body

Example request

Response

Get a race

Path parameters

Example request

Response

Update a race

Path parameters

Request body

Example request

Response

Delete a race

Path parameters

Example request

Response