Quick Start — Docs

Choose your integration

TrueZone is available in three forms:

Method	Best for	Latency
REST API	Server-to-server, quickest integration	~200ms per session
WASM/npm	Browser or Node.js, no network dependency	~50ms per session
C++ SDK	Embedded 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)

[
  {"time": 0, "hr": 80, "speed": 2.5},
  {"time": 1, "hr": 82, "speed": 2.5},
  {"time": 2, "hr": 85, "speed": 2.6}
]

Note: in the actual API request, both data and settings must be stringified JSON strings inside the outer JSON object. See Code Examples for complete request formatting.

2. Configure settings

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

{
  "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

See Code Examples for complete curl, Python, and JavaScript examples. The request body wraps settings and data as stringified JSON strings.

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:

{
  "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

Input Format — all settings options and data requirements
Output Format — complete result schema
Derived Metrics — the full stats output
Code Examples — Python, JavaScript, curl