Vos données de l’app Santé, en REST.

Faites votre première requête

1. Abonnez-vous à Pro dans l’app telo pour iPhone, sous Compte → Formule, puis synchronisez votre historique.
2. Ouvrez Compte dans le tableau de bord web et créez une clé pour votre projet. Enregistrez-la tout de suite : le secret complet n’est affiché qu’une seule fois.
3. Définissez TELO_API_KEY dans l’environnement de votre serveur ou dans votre terminal local, puis lancez la requête ci-dessous.

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

Authentification

Envoyez Authorization: Bearer <key> à chaque requête. Chaque clé ne lit que son propre compte. Conservez-la sur votre serveur ou votre machine locale, jamais dans du code exécuté dans le navigateur, un dépôt public ou une URL. Les cookies et les jetons de l’iPhone n’authentifient pas cette API.

Créez jusqu’à cinq clés et révoquez chaque projet indépendamment dans Compte. La révocation reste possible après l’expiration de Pro. Un abonnement Pro payant est requis, même pour les comptes fondateurs ; les remboursements et les changements d’abonnement suivent le cache de facturation existant, jusqu’à 15 minutes, avec invalidation par webhook.

Endpoints

URL de base : https://telo.health/api/v1. Chaque endpoint utilise GET et renvoie le même JSON que l’outil de lecture MCP correspondant, sans l’enveloppe MCP. Les dates sont au format YYYY-MM-DD. Les listes sont séparées par des virgules ; les booléens valent true ou false. Les paramètres inconnus ou répétés sont refusés.

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"

Exemples de code

Les exemples lisent uniquement le catalogue. Votre clé d’API va dans l’environnement, pas dans le fichier source. Les échecs HTTP doivent être gérés avant d’utiliser la réponse.

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);

Lire la réponse

Réponse d’exemple pour query_daily, avec des données fictives :

{
  "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 compte les jours avec des valeurs enregistrées ; days_expected décrit la couverture calendaire demandée. Une donnée manquante et null ne valent pas zéro. Conservez les unités et le décalage horaire local des horodatages. L’API lit ce que l’iPhone a synchronisé ; l’appeler ne déclenche pas de synchronisation. Les résumés d’entraînement sont permanents, tandis que les séries brutes sont conservées 30 jours. Le GPS n’est pas inclus.

Limites et pagination

• 60 requêtes par minute et par compte, partagées par toutes ses clés. En cas de 429, attendez le nombre de secondes indiqué dans Retry-After.
• Au plus 3 660 jours par requête de dates, ou 366 pour derived_metrics. query_daily accepte jusqu’à 256 noms de métriques séparés par des virgules.
• Les lectures par date renvoient jusqu’à 500 lignes. Si truncated vaut true, ignorez la réponse partielle et demandez moins de métriques ou des plages plus courtes, sans chevauchement et alignées sur des semaines ou des mois complets. Ne traitez pas une moyenne partielle comme une période complète.
• workout_detail utilise des valeurs next_offset et next_event_offset distinctes. Suivez-les indépendamment jusqu’à ce que les deux soient null. Valeurs par défaut : offset=0, event_offset=0, limit=360 ; limit vaut au plus 500. Un metrics= vide renvoie les métadonnées et les événements sans séries.

Erreurs

400

Paramètres, dates ou plage invalides. Consultez la référence OpenAPI.

401

Clé personnelle absente, invalide ou révoquée. Créez une nouvelle clé si nécessaire.

403

Aucun abonnement Pro payant n’est actif. Vérifiez Compte → Formule sur l’iPhone.

429

Limite de requêtes atteinte. Attendez le nombre de secondes de Retry-After avant de réessayer.

500

Erreur interne. Réessayez plus tard ; n’interprétez pas la réponse comme une absence de données de santé.

503

La vérification de l’abonnement est indisponible. Réessayez plus tard.