Skip to content

API reference

The full reference for every endpoint, request schema, and response shape. The spec is also available as a machine-readable OpenAPI 3.1 document. Each API base URL also serves the spec of the version it runs at /v1/openapi.yaml, with a browsable copy at /docs; neither needs a key.

Recent changes

  • 11.9.1
    • Penalties have serving (true while the athlete is serving the approved penalty at a penalty box or a stop-and-go; a paused serve is not serving) and serveStartedAt (when the running serve started, or null). penaltyStatus stays approved until served.
    • New webhook events penalty.serveStarted and penalty.serveStopped — see Webhooks.
  • 11.9.0
    • Four new race fields, all still editable after the race starts:
      • penaltySelfCorrectMinutes (0–60, default 0 = off) — for this many minutes after reporting a penalty, and until the penalty box acts on it, the official who reported it may cancel it or change its athlete number.
      • penaltyTypeTimes — serve times for specific penalty types on this race, as [{"penaltyType": "<type id>", "seconds": 90}]: at most 50 entries, each type once, 1–3600 seconds. An entry replaces penaltyTimeS (or draftingTimeS for drafting and blue-card types) for that type. [] removes every override.
      • penaltyBoxWalkInEnabled and bikePenaltyBoxWalkInEnabled (default false) — walk-in serves in the run or the bike penalty box. Each needs its box: turning one on while penaltyBoxEnabled or bikePenaltyBoxEnabled is off returns 400.
    • Penalties have walkIn (served at the penalty box before any referee's report; its timestamp is when the serve started) and mergedWalkInId (the walk-in this referee's report absorbed, or null). A merged walk-in is cancelled, so it no longer appears in the penalty list.
    • New webhook events penalty.merged and penalty.unmerged — see Webhooks.
    • A published penalty that is cancelled, declined or put under protest sends penalty.statusChanged with its new penaltyStatus.
    • Penalty webhooks carry the same fields as the penalty list, plus penaltyType, now the type's id.
    • Races return penaltyBoxAcceptRequired.
    • Webhook subscriptions return their times as ISO 8601 strings.
    • PATCH /v1/events/{eventId}/webhooks/{webhookId} takes enabled: true switches a disabled subscription back on (same secret, the failure count from zero), false switches it off.
    • A delivery's status is delivered or failed.
    • A revoked key stops working within about 10 seconds (was 60).
  • 11.8.3
    • Replayed writes carry Idempotent-Replayed: true, a retry while the first attempt is still running returns 409, and the API returns 503 with Retry-After when it briefly can't check rate limits.
    • Listing a webhook's deliveries works, and org keys only reach events of their own organisation.
  • 11.8.1 — Races carry checkinType, the race's athlete check-in type.
  • 10.0.0 — Races and race webhooks carry a read-only status: notActive, active (no penalty or incident recorded yet), running (penalties or incidents recorded) or finished (stopped after that).