Getting Started

Quick Start

Send your first request and get a physiological profile in 5 minutes.

Choose your integration

TrueZone is available in three forms:

MethodBest forLatency
REST APIServer-to-server, quickest integration~200ms per session
WASM/npmBrowser or Node.js, no network dependency~50ms per session
C++ SDKEmbedded systems, maximum performance~5ms per session

This guide uses the REST API. See Code Examples for WASM and C++ usage.

1. Prepare your data

You need timestamped heart rate data. Sample rates from 1 Hz down to once every 6 seconds are supported:

  • time — seconds from start (timestamps, not necessarily consecutive)
  • hr — heart rate in bpm
  • speed — speed in m/s (required for variable-speed activities; for fixed-speed tests, set fixedSpeed: true and speed once in settings instead)
{
  "data": "[{\"time\":0,\"hr\":80,\"speed\":2.5},{\"time\":1,\"hr\":82,\"speed\":2.5}, ...]"
}

Note: data and settings are stringified JSON inside the outer JSON object.

2. Configure settings

At minimum, specify whether the session is at a fixed speed:

{
  "settings": "{\"fixedSpeed\":false,\"fit\":true,\"returnPrediction\":true}"
}

Set fit: true to extract parameters from the data. See Input Format for all options.

3. Send the request

curl -X POST $ENDPOINT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"settings":"{\"fixedSpeed\":false,\"fit\":true}","data":"[{\"time\":0,\"hr\":80,\"speed\":2.5},{\"time\":60,\"hr\":140,\"speed\":2.5}]"}'

4. Read the result

{
  "result": {
    "E": 0.65,
    "Vmax": 4.71,
    "P": 185,
    "confidence": 0.82,
    "trueE": 0.64,
    "trueVmax": 4.68,
    "trueP": 184,
    "trueConfidence": 3.5
  }
}

The result contains both single-session estimates (E, Vmax, P) and Bayesian-refined estimates (trueE, trueVmax, trueP). Always use the true values — they incorporate evidence from all previous sessions via the memory system.

  • trueE (Endurance): 0–1 scale. Higher = greater aerobic capacity and fatigue resistance.
  • trueVmax (Maximum speed): m/s. Absolute maximum speed. All thresholds and zones are derived from E and Vmax.
  • trueP (HRmax): bpm. Model-predicted maximum heart rate.

For the first session with a new user, the true values equal the single-session values. As you pass memory between sessions, they refine. See Bayesian Memory for how this works and Understanding E, Vmax, P for interpretation.

5. Get derived metrics

Add returnStats: true plus demographics to get the full profile:

{
  "settings": "{\"fixedSpeed\":false,\"fit\":true,\"returnStats\":true,\"weight\":75,\"height\":178,\"age\":32,\"gender\":\"male\",\"sport\":\"running\"}"
}

This adds a stats object to the result with VO2max, training zones, race predictions, energy expenditure, recovery kinetics, and more. See Derived Metrics.

Next steps

Authentication →