I tuoi dati dell’app Salute, via REST.

Fai la tua prima richiesta

1. Abbonati a Pro nell’app telo per iPhone in Account → Piano, poi sincronizza il tuo storico.
2. Apri Account nella dashboard web e crea una chiave per il tuo progetto. Salvala subito: il segreto completo viene mostrato una sola volta.
3. Imposta TELO_API_KEY nell’ambiente del tuo server o nella shell locale, poi esegui la richiesta qui sotto.

curl --fail-with-body 'https://telo.health/api/v1/list_metrics' \
  -H "Authorization: Bearer $TELO_API_KEY"

Autenticazione

Invia Authorization: Bearer <chiave> in ogni richiesta. Ogni chiave legge solo il proprio account. Conservala sul tuo server o sul tuo computer, mai nel codice del browser, in un repository pubblico o in un URL. I cookie e i token dell’iPhone non autenticano questa API.

Crea fino a cinque chiavi e revoca ogni progetto in modo indipendente in Account. La revoca resta disponibile anche dopo la scadenza di Pro. Serve un abbonamento Pro a pagamento anche per gli account fondatori; rimborsi e modifiche all’abbonamento seguono la cache di fatturazione esistente, fino a 15 minuti, con invalidazione tramite webhook.

Endpoint

URL di base: https://telo.health/api/v1. Ogni endpoint usa GET e restituisce lo stesso payload JSON del tool di lettura MCP corrispondente, senza l’involucro MCP. Le date usano YYYY-MM-DD. Le liste usano le virgole; i booleani usano true o false. I parametri sconosciuti o ripetuti vengono rifiutati.

curl --fail-with-body 'https://telo.health/api/v1/data_status' \
  -H "Authorization: Bearer $TELO_API_KEY"

curl --fail-with-body 'https://telo.health/api/v1/list_metrics' \
  -H "Authorization: Bearer $TELO_API_KEY"

curl --fail-with-body 'https://telo.health/api/v1/query_daily?metrics=steps&from=2026-11-01&to=2026-11-08&granularity=day' \
  -H "Authorization: Bearer $TELO_API_KEY"

curl --fail-with-body 'https://telo.health/api/v1/sessions?kind=workout&from=2026-11-01&to=2026-11-08' \
  -H "Authorization: Bearer $TELO_API_KEY"

curl --fail-with-body 'https://telo.health/api/v1/workout_detail?uuid=WORKOUT_UUID&limit=500' \
  -H "Authorization: Bearer $TELO_API_KEY"

curl --fail-with-body 'https://telo.health/api/v1/derived_metrics?from=2026-11-01&to=2026-11-08&include_trimp=true' \
  -H "Authorization: Bearer $TELO_API_KEY"

Esempi di codice

Gli esempi leggono solo il catalogo. La tua chiave API va nell’ambiente, non nel file sorgente. Gestisci gli errori HTTP prima di usare la risposta.

Python

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://telo.health/api/v1/list_metrics",
    headers={"Authorization": "Bearer " + os.environ["TELO_API_KEY"]},
)
# urlopen raises HTTPError for non-success responses.
with urlopen(request, timeout=30) as response:
    catalog = json.load(response)
print(catalog)

JavaScript (Node.js)

// Node.js, server-side only.
const response = await fetch("https://telo.health/api/v1/list_metrics", {
  headers: { Authorization: `Bearer ${process.env.TELO_API_KEY}` },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`telo HTTP ${response.status}`);
const catalog = await response.json();
console.log(catalog);

Come leggere la risposta

Risposta illustrativa di query_daily, con dati fittizi:

{
  "rows": [
    {
      "period": "2026-11-01",
      "metric": "steps",
      "unit": "count",
      "value": 8200,
      "aggregation": "sum",
      "days_present": 1,
      "days_expected": 1,
      "period_start": "2026-11-01",
      "period_end": "2026-11-01",
      "daily_min": 8200,
      "daily_max": 8200
    }
  ],
  "truncated": false
}

days_present conta i giorni con valori salvati; days_expected descrive la copertura di calendario richiesta. Dati mancanti e null non sono zero. Mantieni le unità e l’offset locale dei timestamp. L’API legge ciò che l’iPhone ha sincronizzato; chiamarla non avvia una sincronizzazione. I riepiloghi degli allenamenti sono permanenti, mentre le serie grezze vengono conservate per 30 giorni. Il GPS non è incluso.

Limiti e paginazione

• 60 richieste al minuto per account, condivise tra tutte le sue chiavi. Con un 429, attendi i secondi indicati in Retry-After.
• Al massimo 3.660 giorni per richiesta per date, o 366 per derived_metrics. query_daily accetta fino a 256 nomi di metriche separati da virgole.
• Le letture per date restituiscono al massimo 500 righe. Se truncated è true, scarta la risposta parziale e chiedi meno metriche o intervalli più piccoli e non sovrapposti, allineati a settimane o mesi completi. Non trattare una media parziale come un periodo completo.
• workout_detail usa valori separati di next_offset e next_event_offset. Seguili in modo indipendente finché entrambi non sono null. Valori predefiniti: offset=0, event_offset=0, limit=360; limit è al massimo 500. Un metrics= vuoto restituisce metadati ed eventi senza serie.

Errori

400

Parametri, date o intervallo non validi. Controlla il riferimento OpenAPI.

401

Chiave personale mancante, non valida o revocata. Se serve, crea una nuova chiave.

403

Non c’è un abbonamento Pro a pagamento attivo. Controlla Account → Piano sull’iPhone.

429

Limite di richieste raggiunto. Attendi i secondi di Retry-After prima di riprovare.

500

Errore interno. Riprova più tardi; non interpretare la risposta come assenza di dati di salute.

503

La verifica dell’abbonamento non è disponibile. Riprova più tardi.