{"openapi":"3.1.0","info":{"title":"HYROX Results Developer API","version":"1.0.0","description":"High-performance, edge-accelerated REST API for HYROX seasons, race events, division leaderboards, athlete career history, and station splits. Designed for sports mobile apps, analytics dashboards, and training pacing simulators.","contact":{"name":"HYROX API Developer Support","url":"https://hyroxresultsapi.com"}},"servers":[{"url":"/","description":"Current Environment Server"},{"url":"https://hyroxresultsapi.com","description":"Production Global Edge"}],"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"version":{"type":"string","example":"1.0.0"},"database":{"type":"string","example":"connected"},"total_events":{"type":"number","example":157},"total_athletes":{"type":"number","example":1339665},"latency_ms":{"type":"number","example":5},"timestamp":{"type":"string","example":"2026-09-22T02:45:00.000Z"}},"required":["status","version","database","total_events","total_athletes","latency_ms","timestamp"]},"EventItem":{"type":"object","properties":{"id":{"type":"string","example":"shenzhen-2026"},"name":{"type":"string","example":"HYROX Shenzhen 2026"},"city":{"type":"string","example":"Shenzhen"},"country":{"type":"string","example":"China"},"country_code":{"type":"string","example":"CN"},"venue":{"type":"string","nullable":true,"example":"Shenzhen World Exhibition & Convention Center"},"date":{"type":"string","example":"2026-08-15"},"end_date":{"type":"string","nullable":true,"example":"2026-08-16"},"season":{"type":"string","nullable":true,"example":"26/27"},"status":{"type":"string","example":"completed"},"athletes_count":{"type":"number","example":11716},"course_map_url":{"type":"string","nullable":true,"example":null},"lap_instructions":{"type":"string","nullable":true,"example":null}},"required":["id","name","city","country","country_code","venue","date","end_date","season","status","athletes_count","course_map_url","lap_instructions"]},"EventsListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventItem"}},"pagination":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":50},"total_events":{"type":"number","example":157},"total_pages":{"type":"number","example":4}},"required":["page","limit","total_events","total_pages"]}},"required":["success","data","pagination"]},"EventDetailResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"allOf":[{"$ref":"#/components/schemas/EventItem"},{"type":"object","properties":{"division_breakdown":{"type":"array","items":{"type":"object","properties":{"division":{"type":"string","example":"HYROX MEN"},"teams_count":{"type":"number","example":1277},"athletes_count":{"type":"number","example":1277}},"required":["division","teams_count","athletes_count"]}}},"required":["division_breakdown"]}]}},"required":["success","data"]},"AthleteResultItem":{"type":"object","properties":{"id":{"type":"number","example":45012},"race_id":{"type":"string","example":"shenzhen-2026"},"bib_number":{"type":"string","nullable":true,"example":"1042"},"full_name":{"type":"string","example":"Hunter McIntyre"},"nationality":{"type":"string","nullable":true,"example":"USA"},"gender":{"type":"string","nullable":true,"example":"M"},"age_group":{"type":"string","nullable":true,"example":"30-34"},"division":{"type":"string","example":"HYROX PRO MEN"},"total_time":{"type":"string","nullable":true,"example":"00:54:07"},"overall_rank":{"type":"number","nullable":true,"example":1},"division_rank":{"type":"number","nullable":true,"example":1},"age_group_rank":{"type":"number","nullable":true,"example":1},"roxzone":{"type":"string","nullable":true,"example":"00:03:12"}},"required":["id","race_id","bib_number","full_name","nationality","gender","age_group","division","total_time","overall_rank","division_rank","age_group_rank","roxzone"]},"ResultsListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"race_id":{"type":"string","example":"shenzhen-2026"},"filters":{"type":"object","properties":{"division":{"type":"string","nullable":true},"age_group":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"sort_by":{"type":"string"},"order":{"type":"string"}},"required":["division","age_group","gender","sort_by","order"]},"pagination":{"type":"object","properties":{"page":{"type":"number","example":1},"limit":{"type":"number","example":50},"total_athletes":{"type":"number","example":1284},"total_pages":{"type":"number","example":26}},"required":["page","limit","total_athletes","total_pages"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AthleteResultItem"}}},"required":["success","race_id","filters","pagination","data"]},"AthleteProfile":{"type":"object","properties":{"id":{"type":"number","example":45012},"full_name":{"type":"string","example":"Hunter McIntyre"},"bib_number":{"type":"string","nullable":true,"example":"1042"},"nationality":{"type":"string","nullable":true,"example":"USA"},"gender":{"type":"string","nullable":true,"example":"M"},"age_group":{"type":"string","nullable":true,"example":"30-34"},"division":{"type":"string","example":"HYROX PRO MEN"},"total_time":{"type":"string","nullable":true,"example":"00:54:07"},"overall_rank":{"type":"number","nullable":true,"example":1},"division_rank":{"type":"number","nullable":true,"example":1}},"required":["id","full_name","bib_number","nationality","gender","age_group","division","total_time","overall_rank","division_rank"]},"CareerHistoryItem":{"type":"object","properties":{"id":{"type":"number","example":45012},"race_id":{"type":"string","example":"mumbai-2026"},"race_name":{"type":"string","example":"HYROX Mumbai 2026"},"date":{"type":"string","nullable":true,"example":"2026-02-07"},"division":{"type":"string","example":"HYROX PRO MEN"},"total_time":{"type":"string","nullable":true,"example":"00:54:07"},"overall_rank":{"type":"number","nullable":true,"example":1},"division_rank":{"type":"number","nullable":true,"example":1}},"required":["id","race_id","race_name","date","division","total_time","overall_rank","division_rank"]},"SplitsBreakdown":{"type":"object","properties":{"run_1":{"type":"string","nullable":true,"example":"00:04:12"},"skierg":{"type":"string","nullable":true,"example":"00:03:55"},"run_2":{"type":"string","nullable":true,"example":"00:04:20"},"sled_push":{"type":"string","nullable":true,"example":"00:02:45"},"run_3":{"type":"string","nullable":true,"example":"00:04:30"},"sled_pull":{"type":"string","nullable":true,"example":"00:03:30"},"run_4":{"type":"string","nullable":true,"example":"00:04:40"},"burpee_jumps":{"type":"string","nullable":true,"example":"00:03:15"},"run_5":{"type":"string","nullable":true,"example":"00:04:45"},"rowing":{"type":"string","nullable":true,"example":"00:04:02"},"run_6":{"type":"string","nullable":true,"example":"00:04:50"},"farmers_carry":{"type":"string","nullable":true,"example":"00:01:45"},"run_7":{"type":"string","nullable":true,"example":"00:04:55"},"sandbag_lunges":{"type":"string","nullable":true,"example":"00:03:10"},"run_8":{"type":"string","nullable":true,"example":"00:05:05"},"wall_balls":{"type":"string","nullable":true,"example":"00:03:40"},"roxzone":{"type":"string","nullable":true,"example":"00:03:12"},"total_time":{"type":"string","nullable":true,"example":"01:02:21"},"total_seconds":{"type":"number","example":3741}},"required":["run_1","skierg","run_2","sled_push","run_3","sled_pull","run_4","burpee_jumps","run_5","rowing","run_6","farmers_carry","run_7","sandbag_lunges","run_8","wall_balls","roxzone","total_time","total_seconds"]},"DivisionStatsResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"division":{"type":"string","example":"HYROX PRO MEN"},"sample_size":{"type":"number","example":4500},"total_time_benchmarks":{"type":"object","properties":{"median":{"type":"string","example":"01:08:42"},"p10":{"type":"string","example":"00:58:14"},"p25":{"type":"string","example":"01:03:30"},"p50":{"type":"string","example":"01:08:42"},"p75":{"type":"string","example":"01:15:10"},"p90":{"type":"string","example":"01:23:45"}},"required":["median","p10","p25","p50","p75","p90"]},"station_medians":{"type":"object","additionalProperties":{"type":"string"},"example":{"skierg":"00:03:52","sled_push":"00:02:40","sled_pull":"00:03:35","burpee_jumps":"00:03:45","rowing":"00:04:05","farmers_carry":"00:01:48","sandbag_lunges":"00:03:15","wall_balls":"00:03:55","roxzone":"00:04:20"}}},"required":["success","division","sample_size","total_time_benchmarks","station_medians"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["System"],"summary":"System health & Turso database connectivity check","responses":{"200":{"description":"API & Database are healthy and fully operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/events":{"get":{"tags":["Events"],"summary":"List all HYROX events (past, live, upcoming)","parameters":[{"schema":{"type":"string","description":"Season code (e.g. 24/25, 25/26, 26/27)","example":"26/27"},"required":false,"name":"season","in":"query"},{"schema":{"type":"string","enum":["completed","live","upcoming"],"example":"completed"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"2-letter country code","example":"US"},"required":false,"name":"country_code","in":"query"},{"schema":{"type":"string","description":"Search term by city or event name","example":"Shenzhen"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","default":"1","example":"1"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","default":"50","example":"50"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of events with metadata & pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsListResponse"}}}}}}},"/v1/events/{id}":{"get":{"tags":["Events"],"summary":"Get single event detail & division athlete counts","parameters":[{"schema":{"type":"string","description":"Unique race ID slug","example":"shenzhen-2026"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Detailed event metadata and participant breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetailResponse"}}}},"404":{"description":"Event not found"}}}},"/v1/events/{id}/results":{"get":{"tags":["Leaderboards"],"summary":"Get paginated race results & leaderboards with instant sorting","parameters":[{"schema":{"type":"string","description":"Race ID slug","example":"shenzhen-2026"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"HYROX PRO MEN"},"required":false,"name":"division","in":"query"},{"schema":{"type":"string","example":"30-34"},"required":false,"name":"age_group","in":"query"},{"schema":{"type":"string","enum":["M","W","X"],"example":"M"},"required":false,"name":"gender","in":"query"},{"schema":{"type":"string","enum":["rank","time","name"],"default":"rank","example":"rank"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","example":"asc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","default":"1","example":"1"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","default":"50","example":"50"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultsListResponse"}}}},"404":{"description":"Race not found or has zero results"}}}},"/v1/athletes/search":{"get":{"tags":["Athletes"],"summary":"Instant athlete search by name or bib number across 1.34M athletes","parameters":[{"schema":{"type":"string","minLength":2,"description":"Athlete name search query","example":"Hunter"},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","description":"Exact bib number","example":"1042"},"required":false,"name":"bib","in":"query"},{"schema":{"type":"string","default":"20","example":"20"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results matching query","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"race_id":{"type":"string"},"bib_number":{"type":"string","nullable":true},"full_name":{"type":"string"},"nationality":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"age_group":{"type":"string","nullable":true},"division":{"type":"string"},"total_time":{"type":"string","nullable":true},"overall_rank":{"type":"number","nullable":true}},"required":["id","race_id","bib_number","full_name","nationality","gender","age_group","division","total_time","overall_rank"]}}},"required":["success","count","data"]}}}}}}},"/v1/athletes/{id}":{"get":{"tags":["Athletes"],"summary":"Get athlete profile, career history & personal bests","parameters":[{"schema":{"type":"string","description":"Athlete result record ID","example":"45012"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Athlete career profile with race history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"athlete":{"$ref":"#/components/schemas/AthleteProfile"},"career_history":{"type":"array","items":{"$ref":"#/components/schemas/CareerHistoryItem"}}},"required":["success","athlete","career_history"]}}}},"404":{"description":"Athlete record not found"}}}},"/v1/athletes/{id}/splits":{"get":{"tags":["Athletes"],"summary":"Get full 16-station split breakdown & Roxzone time","parameters":[{"schema":{"type":"string","description":"Athlete result record ID","example":"45012"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"All 8 runs, 8 workouts and Roxzone splits with seconds conversion","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"athlete":{"type":"object","properties":{"id":{"type":"number"},"full_name":{"type":"string"},"race_id":{"type":"string"},"division":{"type":"string"}},"required":["id","full_name","race_id","division"]},"splits":{"$ref":"#/components/schemas/SplitsBreakdown"}},"required":["success","athlete","splits"]}}}},"404":{"description":"Athlete record not found"}}}},"/v1/stats/divisions/{division}":{"get":{"tags":["Simulator & Stats"],"summary":"Get precomputed division pacing benchmarks, medians & percentiles","parameters":[{"schema":{"type":"string","description":"Division name","example":"HYROX PRO MEN"},"required":true,"name":"division","in":"path"}],"responses":{"200":{"description":"Pacing benchmarks and percentile distribution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionStatsResponse"}}}},"404":{"description":"Division not found"}}}},"/api/health":{"get":{"tags":["System"],"summary":"System health & Turso database connectivity check","responses":{"200":{"description":"API & Database are healthy and fully operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/events":{"get":{"tags":["Events"],"summary":"List all HYROX events (past, live, upcoming)","parameters":[{"schema":{"type":"string","description":"Season code (e.g. 24/25, 25/26, 26/27)","example":"26/27"},"required":false,"name":"season","in":"query"},{"schema":{"type":"string","enum":["completed","live","upcoming"],"example":"completed"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"2-letter country code","example":"US"},"required":false,"name":"country_code","in":"query"},{"schema":{"type":"string","description":"Search term by city or event name","example":"Shenzhen"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","default":"1","example":"1"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","default":"50","example":"50"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of events with metadata & pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsListResponse"}}}}}}},"/api/v1/events/{id}":{"get":{"tags":["Events"],"summary":"Get single event detail & division athlete counts","parameters":[{"schema":{"type":"string","description":"Unique race ID slug","example":"shenzhen-2026"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Detailed event metadata and participant breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetailResponse"}}}},"404":{"description":"Event not found"}}}},"/api/v1/events/{id}/results":{"get":{"tags":["Leaderboards"],"summary":"Get paginated race results & leaderboards with instant sorting","parameters":[{"schema":{"type":"string","description":"Race ID slug","example":"shenzhen-2026"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"HYROX PRO MEN"},"required":false,"name":"division","in":"query"},{"schema":{"type":"string","example":"30-34"},"required":false,"name":"age_group","in":"query"},{"schema":{"type":"string","enum":["M","W","X"],"example":"M"},"required":false,"name":"gender","in":"query"},{"schema":{"type":"string","enum":["rank","time","name"],"default":"rank","example":"rank"},"required":false,"name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","example":"asc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"string","default":"1","example":"1"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","default":"50","example":"50"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated leaderboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultsListResponse"}}}},"404":{"description":"Race not found or has zero results"}}}},"/api/v1/athletes/search":{"get":{"tags":["Athletes"],"summary":"Instant athlete search by name or bib number across 1.34M athletes","parameters":[{"schema":{"type":"string","minLength":2,"description":"Athlete name search query","example":"Hunter"},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","description":"Exact bib number","example":"1042"},"required":false,"name":"bib","in":"query"},{"schema":{"type":"string","default":"20","example":"20"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results matching query","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"race_id":{"type":"string"},"bib_number":{"type":"string","nullable":true},"full_name":{"type":"string"},"nationality":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"age_group":{"type":"string","nullable":true},"division":{"type":"string"},"total_time":{"type":"string","nullable":true},"overall_rank":{"type":"number","nullable":true}},"required":["id","race_id","bib_number","full_name","nationality","gender","age_group","division","total_time","overall_rank"]}}},"required":["success","count","data"]}}}}}}},"/api/v1/athletes/{id}":{"get":{"tags":["Athletes"],"summary":"Get athlete profile, career history & personal bests","parameters":[{"schema":{"type":"string","description":"Athlete result record ID","example":"45012"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Athlete career profile with race history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"athlete":{"$ref":"#/components/schemas/AthleteProfile"},"career_history":{"type":"array","items":{"$ref":"#/components/schemas/CareerHistoryItem"}}},"required":["success","athlete","career_history"]}}}},"404":{"description":"Athlete record not found"}}}},"/api/v1/athletes/{id}/splits":{"get":{"tags":["Athletes"],"summary":"Get full 16-station split breakdown & Roxzone time","parameters":[{"schema":{"type":"string","description":"Athlete result record ID","example":"45012"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"All 8 runs, 8 workouts and Roxzone splits with seconds conversion","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"athlete":{"type":"object","properties":{"id":{"type":"number"},"full_name":{"type":"string"},"race_id":{"type":"string"},"division":{"type":"string"}},"required":["id","full_name","race_id","division"]},"splits":{"$ref":"#/components/schemas/SplitsBreakdown"}},"required":["success","athlete","splits"]}}}},"404":{"description":"Athlete record not found"}}}},"/api/v1/stats/divisions/{division}":{"get":{"tags":["Simulator & Stats"],"summary":"Get precomputed division pacing benchmarks, medians & percentiles","parameters":[{"schema":{"type":"string","description":"Division name","example":"HYROX PRO MEN"},"required":true,"name":"division","in":"path"}],"responses":{"200":{"description":"Pacing benchmarks and percentile distribution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DivisionStatsResponse"}}}},"404":{"description":"Division not found"}}}}}}