GET /api/v1/events/{eventId}/racesscope: events:read

List races

API v1 Last updated 2026-09-30 View as Markdown

#List races

An event's races. Identical data to the races field on Get event — a separate endpoint for callers who only need the race list without the rest of the event detail.

#Headers

Header	Required	Value
`Authorization`	yes	`Bearer <access_token>`

#Path parameters

Param	Type	Note
`eventId`	UUID	`404 EVENT_NOT_FOUND` if unknown / another club's / not published

#Request

cURL

curl -s https://sail-club-server.cloud.run/api/v1/events/1143117a-9c2b-4e7a-8f1d-2b6a9c4e7f10/races \
  -H "Authorization: Bearer $TOKEN"

JavaScript/TypeScript (fetch)

const res = await fetch(`https://sail-club-server.cloud.run/api/v1/events/${eventId}/races`, {
  headers: { Authorization: `Bearer ${token}` },
});
const races = await res.json();

Python (requests)

res = requests.get(
    f"https://sail-club-server.cloud.run/api/v1/events/{event_id}/races",
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)
races = res.json()

C# (HttpClient)

var res = await client.GetAsync($"/api/v1/events/{eventId}/races");
res.EnsureSuccessStatusCode();
var races = await res.Content.ReadFromJsonAsync<List<PublicRaceSummaryDto>>();

PHP

<?php
$ch = curl_init("https://sail-club-server.cloud.run/api/v1/events/$eventId/races");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"]]);
$races = json_decode(curl_exec($ch), true);

#Response

[
  {
    "id": "9a1c0d2b-7e4a-46f8-9c1d-2e3f9a1c0d2b",
    "name": "Race 1",
    "scheduledDate": "2026-10-11T10:00:00Z",
    "status": "Completed",
    "hasResults": true,
    "isOfficial": true,
    "resultCount": 42,
    "raceNo": 1,
    "raceType": "Fleet",
    "boatModel": null
  },
  {
    "id": "2b6a9c4e-7f10-4a1c-8d2b-7e4a6f8c1d2e",
    "name": "Race 2",
    "scheduledDate": "2026-10-11T13:00:00Z",
    "status": "Completed",
    "hasResults": true,
    "isOfficial": true,
    "resultCount": 41,
    "raceNo": 2,
    "raceType": "Fleet",
    "boatModel": null
  }
]

200 — same caching headers as every data endpoint; the array itself carries the ETag/Last-Modified.

#Response fields

Full field table: Data models → Race summary. Use each item's id as the raceId for Race results once hasResults is true.

#Errors

HTTP	Code
404	`EVENT_NOT_FOUND`
401	`API_TOKEN_MISSING` / `API_TOKEN_INVALID`
403	`API_SCOPE_MISSING` / `API_IP_NOT_ALLOWED`
429	`RATE_LIMIT_EXCEEDED`
503	`API_UNAVAILABLE`

#Caching

One cache entry per eventId; races only stop changing once hasResults is true for all of them, so it's safe to revalidate on your normal schedule throughout an event and less often afterwards.

Prompt for AI agents ready to paste into an agent

Implement listRaces(eventId) for the Sail Club API.

GET https://sail-club-server.cloud.run/api/v1/events/{eventId}/races
Authorization: Bearer <access_token>

Success 200: an array of { id, name, scheduledDate, status, hasResults, isOfficial, resultCount, raceNo,
  raceType, boatModel, ... } — fetch GET /api/v1/openapi.json for the exact schema.
404 EVENT_NOT_FOUND: unknown/other club's/unpublished event — not retryable.
401/403/429/503: same handling as every other call — see the full-integration prompt on /docs/overview.

For each race where hasResults is true, this is the id to pass to the race-results call
(GET /api/v1/races/{raceId}/results).

Adapt to your actual stack — the endpoint, path param and response shape above are language-neutral.