Skip to content

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
idsUp to 100 race ids, comma-separated
countryISO 3166-1 alpha-2
from, toRaces whose days meet the window: the last race day is on or after from, the first is on or before to
atWhen 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

FieldMeaning
schemaraces/1
idThe race page's slug (/races/{id}). Stable
name, location, official_urlAs the race file has them
country_nameThe name as written
authoritycurated, verified_organizer (a publisher overlay), community (a community race), or reviewed_guide (a published road-race guide's briefing and reviewed facts)
editionlabel ("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)
entryHow 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:

FieldMeaning
keyThe course's identity (?distance= on race pages, training plans and saved races). Never renamed
labelThe organizer's current name, when it differs from key
km, climb_mAs published in the race file
descent_mThe 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_hoursThe overall time limit, or null
date, date_end, start_time, start_placeThe course's own days and start, where they differ from the event's
utmb_category, running_stonesAs the organizer publishes them for the edition
facts_source_url, facts_checked_onWhere the course figures were read
course_lineTrue when the race page has a course line (a hosted file, the organizer's own file, or a verified version)
course_source_urlThe 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
officialThe 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
FieldMeaning
methodopen, draw, qualifier, qualifier-and-draw or invitation
methods_differTrue when courses are won in different ways
summary, edition, time_zone, draw_date, draw_editionAs 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_urlAs listed by the organizer
source_url, checked_onThe organizer's page and the day it was read
statusThe 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

CodeWhen
edition_unsourcedThe file has no dated edition record
date_estimatedThe edition date is estimated, not yet published
courses_carried_forwardThe courses are an earlier edition's
entry_unknownNo entry facts were read
entry_staleThe entry facts are more than 45 days old at at
entry_other_editionThe entry facts describe another edition
descent_unknownPer course: descent is not sourced
cutoff_unknownPer course: no time limit is recorded. Not used for stage races, which have daily limits
stations_other_editionPer course (1.1): the stations are the organizer's list for another edition than the record's

Errors

{ "error": { "code", "message" } }:

HTTPcodeWhen
400bad_atat is not an ISO instant or date
400bad_idsMore than 100 ids, or one with characters other than a–z, 0–9 and -
400bad_countrycountry is not two letters
400bad_datefrom or to is not a date
404not_foundNo race with this id
  • 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_m re-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.