Seus dados do Apple Health, por REST.

Faça sua primeira chamada

1. Assine o Pro no app telo para iPhone em Account → Plan e sincronize seu histórico.
2. Abra Conta no painel web e crie uma chave para seu projeto. Guarde-a agora: o segredo completo aparece uma única vez.
3. Defina TELO_API_KEY no ambiente do seu servidor ou terminal local e execute a chamada abaixo.

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

Autenticação

Envie Authorization: Bearer <chave> em cada chamada. Cada chave lê apenas a própria conta. Guarde-a no servidor ou computador, nunca no código do navegador, num repositório público ou numa URL. Cookies e tokens do iPhone não autenticam esta API.

Crie até cinco chaves e revogue o acesso de cada projeto em Conta. A revogação continua disponível após o Pro expirar. A API exige Pro pago inclusive para contas fundadoras; reembolsos e mudanças da assinatura seguem o cache de cobrança existente, de até 15 minutos, invalidado pelo webhook.

Endpoints

URL base: https://telo.health/api/v1. Todos os endpoints usam GET e devolvem o mesmo JSON da tool de leitura do MCP, sem o envelope MCP. Datas usam YYYY-MM-DD. Listas usam vírgulas; booleanos usam true ou false. Parâmetros desconhecidos ou repetidos são recusados.

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"

Exemplos de código

Os exemplos leem apenas o catálogo. A chave fica no ambiente, não no arquivo de código. Trate erros HTTP antes de usar a resposta.

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

Como ler a resposta

Resposta ilustrativa de query_daily, com dados fictícios:

{
  "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 dias com valores guardados; days_expected descreve a cobertura de calendário pedida. Dados ausentes e null não são zero. Preserve as unidades e o offset local dos timestamps. A API lê o que o iPhone enviou; chamá-la não força sincronização. Resumos de treino são permanentes; séries brutas ficam disponíveis por 30 dias. GPS não é incluído.

Limites e paginação

• 60 chamadas por minuto por conta, somando todas as chaves. Ao receber 429, aguarde os segundos indicados em Retry-After.
• Até 3.660 dias por consulta de datas, ou 366 em derived_metrics. query_daily aceita até 256 nomes de métricas separados por vírgula.
• Leituras por data devolvem até 500 linhas. Se truncated for true, descarte a resposta parcial e peça menos métricas ou intervalos menores sem sobreposição, alinhados a semanas/meses completos. Não trate uma média parcial como um período inteiro.
• workout_detail usa next_offset e next_event_offset separados. Siga os dois independentemente até ambos serem null. Padrões: offset=0, event_offset=0, limit=360; limit vai até 500. metrics= vazio devolve metadados e eventos, sem séries.

Erros

400

Parâmetros, datas ou intervalo inválidos. Confira a referência OpenAPI.

401

Chave pessoal ausente, inválida ou revogada. Crie outra se necessário.

403

A assinatura Pro paga não está ativa. Confira Account → Plan no iPhone.

429

Limite de chamadas atingido. Aguarde os segundos de Retry-After.

500

Erro interno. Tente mais tarde; não interprete a resposta como ausência de dados de saúde.

503

Verificação da assinatura indisponível. Tente mais tarde.