races/1: curated races, their courses and entry facts (read only)
GET · POST · PATCH · DELETE https://api.trailsplits.com/v1
Create projects, issue and rotate keys, and read usage. Sign-in uses your TrailSplits account; the API console is built on these calls.
Contract
Operations
Both are GET on trailsplits.com (the races app). They answer JSON with Access-Control-Allow-Origin: * and Cache-Control: public, max-age=60, s-maxage=300.
GET /api/races/v1/races[?ids=a,b][&country=CH][&from=YYYY-MM-DD][&to=YYYY-MM-DD][&at=…]
GET /api/races/v1/races/{id}[?at=…]
| Parameter | |
|---|---|
ids | Up to 100 race ids, comma-separated |
country | ISO 3166-1 alpha-2 |
from, to | Races whose days meet the window: the last race day is on or after from, the first is on or before to |
at | When to judge the entry state: an ISO-8601 instant, or a date meaning 12:00 UTC. Default: now |
The list answers { schema: "races-list/1", at, count, races: [record…], notice }, in date order. There is no paging at this size: 90 curated races plus the published race guides.
One race answers the record plus notice.
The record
| Field | Meaning |
|---|---|
schema | races/1 |
id | The race page's slug (/races/{id}). Stable |
name, location, official_url | As the race file has them |
country_name | The name as written |
authority | curated, verified_organizer (a publisher overlay), community (a community race), or reviewed_guide (a published road-race guide's briefing and reviewed facts) |
edition | label ("2027"), date, date_end, date_status (confirmed, estimated, or null when the file does not say), course_status (current-edition-verified or carried-forward, with course_source_edition), source_url, checked_on |
courses[] | One per course (below) |
entry | How a place is won (below), or null when it has not been read |
results[] | Official results pages: edition, url, courses (null means every course), via (a timing partner or "UTMB Index"), checked_on |
unknowns[] | { code, message, course? } (below) |
A course:
| Field | Meaning |
|---|---|
key | The course's identity (?distance= on race pages, training plans and saved races). Never renamed |
label | The organizer's current name, when it differs from key |
km, climb_m | As published in the race file |
descent_m | The organizer's stated descent where one is published. Otherwise, since 13 Oct 2026, derived from the course file: the stated climb minus the file's own net rise (file gain − file loss), measured on our line or, for a course still drawn on the organizer's line, on the organizer's file. The net rise does not depend on smoothing, where a file's raw descent does. Null when neither exists. It is never assumed equal to the climb |
cutoff_hours | The overall time limit, or null |
date, date_end, start_time, start_place | The course's own days and start, where they differ from the event's |
utmb_category, running_stones | As the organizer publishes them for the edition |
facts_source_url, facts_checked_on | Where the course figures were read |
course_line | True when the race page has a course line (a hosted file, the organizer's own file, or a verified version) |
course_source_url | The organizer's page for the course, or a verified version's provenance page. Never a direct file link (GPX, KML, FIT, a Drive file, a raw upload): where no page exists it is null. A page link is attribution; where a file was fetched is internal (rights review, 5 Oct 2026). A test fails if any URL in a public record is a direct file link |
official | The organizer's published figures where they were read: km, climb_m, edition, source_url, checked_on. These can differ from the file's measured length; the race page shows both |
| Field | Meaning |
|---|---|
method | open, draw, qualifier, qualifier-and-draw or invitation |
methods_differ | True when courses are won in different ways |
summary, edition, time_zone, draw_date, draw_edition | As read |
windows[] | Per course group: courses, method, requirement, milestones[] |
milestones[] | kind, at, audience, label. at is the organizer's local wall time in time_zone: YYYY-MM-DDTHH:MM, or YYYY-MM-DD when only the day is published. A date-only step never gains a midnight it was not given |
availability[] | What the organizer showed about places on a date: sold_out, waitlist, closed or not_open (1.6), with observed_on and source_url. Observed, never inferred from a closing date. not_open means the organizer showed registration as not open yet, without a date ("Opening soon"); it never means closed, sold out or a guessed opening date. A client that meets a state it does not know shows the organizer's page, never a register action |
alternatives, registration_url, results_url | As listed by the organizer |
source_url, checked_on | The organizer's page and the day it was read |
status | The state at at: phase (RACE-1's EntryPhase, such as draw_open, opens_later, open, closed or sold_out), stale, next_change_at (the next instant the phase can change), and by_course[] (course, phase) whenever an entry window names courses. In that case the event-level phase is often unknown, because the event has no single state, so read by_course |
stale is true when checked_on is more than 45 days before at. An "open" is then not stated as current.
Unknowns
| Code | When |
|---|---|
edition_unsourced | The file has no dated edition record |
date_estimated | The edition date is estimated, not yet published |
courses_carried_forward | The courses are an earlier edition's |
entry_unknown | No entry facts were read |
entry_stale | The entry facts are more than 45 days old at at |
entry_other_edition | The entry facts describe another edition |
descent_unknown | Per course: descent is not sourced |
cutoff_unknown | Per course: no time limit is recorded. Not used for stage races, which have daily limits |
stations_other_edition | Per course (1.1): the stations are the organizer's list for another edition than the record's |
Errors
{ "error": { "code", "message" } }:
| HTTP | code | When |
|---|---|---|
| 400 | bad_at | at is not an ISO instant or date |
| 400 | bad_ids | More than 100 ids, or one with characters other than a–z, 0–9 and - |
| 400 | bad_country | country is not two letters |
| 400 | bad_date | from or to is not a date |
| 404 | not_found | No race with this id |
Related contracts
- Course evidence and the race card (race-course-evidence/1, race-card-composition/1, race-route-card/1) are first-party only and are not linked from this contract. They are on hold for a rights review (program manager, 5 Oct 2026).
Not in this version
- Prices and fees. They are not modelled in the race files; summaries mention them in words.
- Historical results as data. Finish-time percentiles stay a page method.
Versioning
Additive fields may appear in races/1. A change of meaning or a removed field is races/2. Additive revisions are numbered as minors in the changelog; the producer exports the current one as RACES_CONTRACT_MINOR. The minor is documentation only: responses carry schema: "races/1" and never a minor, because every consumer is first-party and reads the schema and the fields. A served contract_minor would come with the first outside consumer (the owner's call), together with portal and release-feed treatment.
Changelog
-
Data, 13 Oct 2026 (no version change):
descent_mre-derived by the rule above on 319 courses in two passes (137 curated courses, then 182 in 57 races). An organizer's stated descent is never overwritten.