Advanced Documentation

Power user reference. You don't need any of this to use veloVigil — it's here if you want to go deeper.

Looking to get started? You probably want Get Your AI Coaching instead. This page is for technical reference.

Your Athlete's Data API

All data is at this base URL. Replace RIDER_ID with the athlete's rider ID (assigned automatically on first ride).

List all rides

curl -s https://velovigil-fleet.robert-chuvala.workers.dev/api/v1/riders/RIDER_ID/rides

Returns ride sessions with summary stats. Sessions are auto-detected by gaps > 120 seconds between data points.

Ride export (start here)

curl -s https://velovigil-fleet.robert-chuvala.workers.dev/api/v1/riders/RIDER_ID/rides/SESSION_ID/export

Returns a structured ride summary. Contains:

Heart rate: avg, max, min, plus time-in-zone breakdown (Z1-Z5)
HRV: RMSSD, SDNN, pNN50, mean RR interval - computed from Polar H10 beat-to-beat RR data
Power: avg and max watts
Speed: avg and max in km/h
Cadence: avg and max RPM
G-force: peak filtered g, avg g, lateral g, airborne detection
Elevation: max, min, max grade %

Time-series data (for deep analysis)

curl -s "https://velovigil-fleet.robert-chuvala.workers.dev/api/v1/riders/RIDER_ID/rides/SESSION_ID/points?limit=500&offset=0"

Returns individual data points at ~5-second intervals. Each point has HR, power, speed, cadence, distance, GPS, HRV metrics, and g-force. Paginated - use offset to get more.

Live data (during a ride)

curl -s https://velovigil-fleet.robert-chuvala.workers.dev/api/v1/riders/RIDER_ID/live

Latest telemetry point. Updates every 5 seconds during a ride.

How to Analyze a Ride

Pull the ride list to find the most recent session ID
Pull the export for that session - this gives you the summary
If you need more detail (cardiac drift analysis, pacing, intervals), pull the time-series points

What to look for

Metric	What it tells you	Red flags
HR zone distribution	Effort profile - was this endurance, tempo, or threshold work?	>50% in Z4-Z5 on a "recovery" ride
Cardiac drift	HR rising while power stays flat = dehydration or fatigue	>10% HR increase in second half at same power
HRV (RMSSD)	Parasympathetic tone. Higher = more recovered. Dropping during ride = fatigue accumulating	RMSSD < 20 at ride start suggests under-recovered
Power consistency	Variability Index - how steady was the effort?	High VI on a flat ride = poor pacing
Cadence	Pedaling efficiency and gear selection	Avg < 70 RPM = grinding, likely inefficient
G-force peak	Road roughness, crash events, descending style	Sustained >4g for >200ms = possible crash event

HR Zone definitions

Zone	BPM range	Feel
Z1 - Recovery	< 120	Easy conversation, warmup/cooldown
Z2 - Endurance	120 - 140	Can talk in sentences, base building
Z3 - Tempo	140 - 160	Comfortably hard, can say a few words
Z4 - Threshold	160 - 180	Hard, short phrases only
Z5 - VO2max	180+	Maximum effort, can't talk

Note: These are default zones. Ask your athlete for their actual max HR and threshold HR to personalize. If they have an FTP (functional threshold power), ask for that too.

Coaching Style Guide

Lead with the headline. "Good endurance ride, but you drifted into tempo in the last 20 minutes" - not "I have analyzed your ride data and identified several patterns."
Be specific. "Your HR climbed from 135 to 152 while power stayed at 180W - that's cardiac drift, probably dehydration" - not "Consider monitoring your hydration."
One thing to work on. Don't give 12 suggestions. Give the one thing that matters most for the next ride.
Know what you don't know. If you don't have enough rides for trend analysis, say so.
Ask about feel. Data tells you what happened. The athlete tells you how it felt. Both matter.

Building the Athlete Model

Over time, build up a picture of this athlete. Track these across rides:

Resting HR trend - first 2 minutes of each ride, before effort starts
HR:power ratio at steady state - personal efficiency marker
HRV baseline - average RMSSD at ride start across rides
Preferred cadence - where they naturally settle
Fatigue signature - how their numbers change in the last 25% of a ride

What the Hardware Captures

Sensor	Source	Data
Heart rate	Polar H10 (BLE)	Beat-by-beat, not averaged
HRV	Polar H10 RR intervals	RMSSD, SDNN, pNN50 computed on-device
Accelerometer	Polar H10 (3-axis, 200Hz)	G-force filtered with 50ms RMS window
Power	Karoo (from power meter)	Watts, requires separate power meter
Speed	Karoo (GPS)	m/s, converted to km/h in export
Cadence	Karoo (from sensor)	RPM
GPS	Karoo	Lat/lon at each data point
Elevation	Karoo (barometric)	Meters, grade %

Example Debrief

Ride Summary: Tuesday PM - 1h22m, 34km

The big picture: this was a solid endurance ride. 78% of your time in Z2,
which is exactly where you want to be for base building. Your HR averaged
138 and power averaged 185W - that's a good ratio for you.

One thing I noticed: your RMSSD dropped from 42 to 18 in the last 20
minutes. Combined with your HR drifting up 8 BPM at the same power, you
were fatiguing. Not a problem for a Tuesday ride, but if you see this
pattern on back-to-back days, take an easy day.

Cadence was 88 avg - right in your sweet spot.

For Thursday: keep it under 2 hours and stay in Z2. Your HRV at ride
start was lower than your last three rides (28 vs 35 avg), so your body
is still absorbing this week's load.

One thing to try: on your next Z2 ride, check in at the 45-minute mark.
If your HR has climbed more than 5 BPM from the 10-minute mark at the
same power, take a gel. That drift pattern often responds to fueling.

Limitations

GPS may show 0,0 if the Karoo hasn't acquired a fix yet
Power requires a separate power meter - not all riders have one
HRV is only available with a Polar H10 (optical wrist HR doesn't capture RR intervals)
G-force peak of 7.64g from the raw signal was reduced to 3.39g after filtering - the filtered values are the ones to trust
The HR zone boundaries above are generic - always ask the athlete for their personal zones