Race Schedule
API

Who this key belongs to

Confirms the key works and names the person behind it, without touching an event. Use it for a connection test: every other route answers 404 for an event you may not see, so a bad key and a wrong event id are otherwise indistinguishable.

No e-mail address is returned, here or anywhere else. displayName is the name its owner set in the app, and is meant for showing which account a desktop client is connected as.

The events this key may manage

Every event whose race schedule the key's owner may manage — the ones their club role covers, plus any they created themselves. Ordered by startDate, newest first, and capped at 200 with no pagination.

Past events are included on purpose: results get typed up days later and a running order gets corrected after the fact.

An owner who may manage nothing gets an empty list and a 200, never a 403. Permissions are re-checked on every request, so an event can leave this list without your key changing.

Read the whole running order

Returns the schedule with every race and lane, including draft schedules and unmasked finish times. resultVisibility reports what the club configured for public display — respect it if you render a spectator-facing scoreboard.

Create the schedule if the event has none

Idempotent. Returns 201 with a fresh schedule, or 200 with the one that already exists — retrying after a timeout is safe.

All three settings default, because the app asks about them deliberately and a machine caller answers none of them: no lane scheme, timed results, full visibility. Send them explicitly if the venue is not a lane course.

Make the running order visible to the crews

POST /schedule creates a draft, which only the event's managers can see. Until you publish, a complete regatta — every race, every lane, every result — reaches nobody following the event.

Idempotent: publishing an already-published schedule is a 200, not an error. 404 if the event has no schedule yet; create one first.

There is no un-publish. Taking a running order back off the crews' phones stays a human action in the app.

Report that a race day is running late

Sets the offset for one race day, so every race of that day which has not been scored is re-estimated at scheduledAt + delayMinutes.

Per day and not per schedule: a regatta spans several days and each slips on its own. venueDay is YYYY-MM-DD in the venue's zone — the same key the app groups races by, and deliberately not derived from a UTC date, which lands on the wrong day across a DST boundary.

Signed, because a day can also run early. Zero clears the offset rather than storing a zero.

This is the one write here that reaches people within the minute: the schedule-delayed push goes to the crews following that day. Setting it on a regatta that has already finished is silent all the same — the notification task only looks at a 30-hour window.

List the crews at this event

Create or update crews

Matches on externalId, then adopts an existing crew with the same name — but only one that carries no externalId of its own. Teams seeded from club registrations carry none, so your first push claims them rather than failing on the unique name index. A crew already held under a different externalId is never adopted: your row is treated as new, hits UNIQUE (eventId, name), and comes back as a 409. Renaming means pushing the new name under the externalId that already owns it.

clubId, boatIndex and sortOrder are preserved when omitted: they tie a crew to a club on this platform and to the registration it came from, and a caller that has never heard of either should not erase both by pushing a name.

Each returned crew carries an outcome telling you which of the three paths it took.

Two failures to tell apart: the same externalId twice in one payload is a 422 with field set to teams[i].externalId, and a name already held under a different externalId is a 409 with no field.

Create or update races

One request, one transaction. Race numbers must be unique across the whole schedule once your payload is applied — not just within the payload — and a violation rejects the entire request rather than leaving a half-written running order.

Adoption matches on raceNumber, the one identifier a schedule built by hand and a schedule pushed by software agree on — but only for a race that carries no externalId yet. A race already held under a different externalId is never adopted; your row is treated as new and then collides on the race number, which is a 409. To renumber, push the new number under the externalId that already owns the race.

Omitted fields are preserved on an existing race. scheduledAt is required when creating one and must carry an explicit UTC offset — a naive timestamp is rejected rather than guessed at.

A race number repeated *within* your payload is a 422 naming races[i].raceNumber. One that collides with a race already in the schedule but absent from your payload is a 409 with no field — detail names the number, and you will have to find it yourself.

Set the lane draw for one race

Send the complete draw. A lane with no teamExternalId is emptied but kept, so the race keeps its start-position structure.

The crew must already exist — push to /teams first. positionLabel defaults to the race's lane scheme, then the schedule's, then the position number.

Seat plans and progression rules cannot be set here. Both belong to the app, and a caller that forgot to echo them back would otherwise erase a lineup by re-pushing a draw.

Post the finish for one race

Send every lane you have a result for in a single call. A place is a statement about the whole field — a time in lane 5 can demote lanes 1 through 4 — so posting lanes one at a time makes every intermediate state a ranking nobody entered, visible to everyone reading the live schedule.

In a timed race, places are derived from the times: send finishTimeMillis and leave finishPlace alone. In a placesOnly race, send finishPlace and no time. Mixing them is rejected rather than silently dropped.

status defaults to finished. Use dns, dnf or dsq where they apply.

A result contradicting the race's mode is a 422 with field set to results — the whole list, not the offending lane. The rule belongs to the race, so there is no one element to blame.

Posting a result for a race scheduled near the current time notifies the crews following it, within about a minute. Backfilling a finished regatta does not.