数据面

设备数据

Cookbook：把穿戴/设备数据写入 Mirobody —— 日聚合、批量 POST /v1/data、带 end_time 的 episode。

你已经接好了穿戴设备 —— 通过 Terra、Junction 或厂商 API —— 样本正流进你的后端。本页是把它们写入 Mirobody 的配方：写入之后，标准化管线和 agent 会像对待任何健康记录一样处理它们。

配方

接收

你的厂商集成送来样本 —— webhook 推送或周期性拉取，厂商提供什么就用什么。

聚合到日级（建议）

高频序列在写入前先聚合为每天一条记录 —— 成本更低，序列也更清晰。Episode 保留自己的时段。

用 POST /v1/data 写入

每次请求最多 500 条，retention 必填 —— 与任何其它结构化写入同一契约。

1. 写入前先聚合（建议）

POST /v1/data 接受任何粒度，但对多数产品，一行对应一条有意义的读数就够了 —— 写入量（和成本）更低，序列也更好理解：

日累计（步数、卡路里、距离）—— 每天一条记录。
连续序列（每隔几分钟采样的心率、SpO₂）—— 先聚合成日级值（如静息或日均心率），需要 min/max 就作为独立指标各写一条。只在产品确实需要时才写更细的粒度。
Episode 型（睡眠、运动）—— 每个 episode 一条记录，用 time + end_time 携带时段（见下）。

2. 批量写入日级记录

curl https://api.mirobody.ai/v1/data \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "user": "alice",
        "retention": "permanent",
        "records": [
          {"indicator": "steps",              "value": 12450,             "time": "2026-07-10T00:00:00Z", "source": "garmin"},
          {"indicator": "resting_heart_rate", "value": 58, "unit": "/min", "time": "2026-07-10T00:00:00Z", "source": "garmin"}
        ]
      }'

每次请求最多 500 条 —— 把一个 Subject 一整天（或一段回填窗口）的数据装进一次调用。用 source 标记厂商来源 —— 你的厂商标记会在读取记录时出现在 comment 字段中。

3. Episode：用 `end_time` 携带时段

睡眠和运动不是时间点读数 —— 它们跨越一个时段。起点放 time，终点放可选的 end_time（均为 ISO 时间戳）：

curl https://api.mirobody.ai/v1/data \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "user": "alice",
        "retention": "permanent",
        "records": [
          {"indicator": "sleep_duration", "value": 7.5, "unit": "h",
           "time": "2026-07-09T23:10:00Z", "end_time": "2026-07-10T06:40:00Z",
           "source": "garmin"}
        ]
      }'

GET /v1/data 每行都会返回 end_time（时间点读数为 null），你的应用可以按时段渲染这个 episode。

4. 标准化自动发生

每次结构化写入都走与手动记录、存储抽取结果相同的标准化管线：识别出的指标名称确定性解析到 LOINC，值解析为 UCUM 单位，记录镜像到 FHIR。低置信度名称会保留为未编码，不会猜测。用 GET /v1/data 读回序列 —— agent 回答时读的也是同一份数据。

Mirobody 刻意不做什么

托管设备 OAuth。连接设备 —— 厂商授权页、token 刷新、webhook 管道 —— 留在你的产品里；每家厂商的流程都不一样，它属于你的 UX。而数据进来之后的一切 —— 存储、标准化、留存、删除、AI —— 是 Mirobody 的职责。

下一步

数据

POST / GET / DELETE /v1/data 的完整契约。

标准化

LOINC / UCUM / FHIR 如何应用，以及未编码行如何处理。