数据 - Mirobody

把结构化记录直接写进数据主体(Subject)的存储，并读回。每次写入都会经过平台的标准化管线 —— 记录读回时带有 LOINC 编码、规范名称、UCUM 归一化的值/单位与 FHIR 镜像。对话智能体用其内置工具读取的正是这同一份数据。健康数据有三种形态 —— 每种形态各有一扇门进来：

数据形态	典型来源	录入方式	端点
结构化读数	设备/穿戴（由你自己接入，日聚合后写入）、手动记录	结构化记录	`POST /v1/data` —— 高频样本先自聚合；episode 型（睡眠、运动）用 `time` + `end_time` 携带时段。见设备数据 cookbook。
文件/照片	化验单、体检报告 PDF、手机拍照	文件上传	`POST /v1/files` —— 自动 OCR 与解析；想同步拿回解析结果用 `POST /v1/extract`
叙事记录	”我头晕头疼”、对话口述	叙事文本	`POST /v1/extract` —— 可量化读数会被抽取；纯叙事返回 `data: []` 加一个 `note`（journal 端点在规划中）

Mirobody 负责托管、标准化并把数据供给 AI —— 采集数据（设备 OAuth、App 侧获取）在你那一侧。

user 字段是租户隔离键。 后端把 (你的账户, user) 映射为内部的数据主体(Subject)；你传入的每个 user 彼此完全隔离。为每个终端用户传入其稳定 id，数据就绝不会串。省略时回落到你账户的默认 Subject。Subject 对 Mirobody 消费端 App 和其他开发者均不可见。

写入记录

POST /v1/data
Authorization: Bearer mb_live_*
Content-Type:  application/json

字段	类型	说明
`records`	array	每条记录 `{indicator, value, unit?, time?, end_time?, source?}`。每次请求最多 500 条。 `end_time`（可选，ISO 时间）标记 episode 的结束 —— 睡眠、运动 —— 其起点为 `time`。`measured_at` / `start_time` 是 `time` 的别名 —— POST /v1/extract 返回的行（字段名为 `measured_at`）可原样转发。
`user`	string	记录所属的 Subject（租户隔离键）。
`retention`	string	必填 —— 没有默认值。取值为 `permanent` / `1h` / `2h` / `6h` / `1d` / `session` 之一（`persistent` 作为 `permanent` 的别名也接受）。小时粒度在写入后按时长自动删除（硬上限 ≤ 24h）。省略它 —— 或传枚举之外的任何值 —— 返回 `400`（`code: invalid_retention`）。
`session_id`	string	`retention=session` 时必填（否则 `400`，`code: invalid_session`）。为记录打上标签，使 `DELETE /v1/sessions/{id}` 能清除它们。

curl https://mirobody-api.thetahealth.ai/v1/data \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "user": "alice",
        "retention": "permanent",
        "records": [
          {"indicator": "fasting_glucose", "value": 5.4, "unit": "mmol/L", "time": "2026-06-16T07:30:00Z"},
          {"indicator": "fasting_glucose", "value": 5.1, "unit": "mmol/L", "time": "2026-06-17T07:25:00Z"}
        ]
      }'

响应 —— standardized 统计写入途中成功解析到 LOINC 编码的记录数：

{ "status": "ok", "ingested": 2, "standardized": 2, "subject": "alice" }

每次写入都会标准化，而不只是存储。 每条记录的值/单位会做 UCUM 解析，指标名称做确定性 LOINC 解析（curated 语料 + embedding —— 不让 LLM 猜码）。见标准化。想在不写入的情况下预览这条管线，请用 POST /v1/extract 的 store=false。

Episode 型（睡眠、运动）

Episode 型记录跨越一个时段而非时间点 —— 起点放 time，终点放可选的 end_time：

curl https://mirobody-api.thetahealth.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"}
        ]
      }'

规模化写入设备数据（日聚合、批量、厂商接入）？见设备数据 cookbook。

读取记录

GET /v1/data?user=alice&indicator=fasting_glucose&limit=100
Authorization: Bearer mb_live_*

Query	说明
`user`	读取哪个 Subject。
`indicator`	可选，按指标名过滤（子串匹配）。
`limit`	`1`–`1000`（默认 `100`）。
`offset`	跳过 N 条用于翻页(排序稳定:最新在前)。`has_more: true` 时用 `offset += limit` 取下一页。

响应为 OpenAI 风格的列表，最新在前。value 是人读字符串（如 "5.4 mmol/L"）；机读字段并列返回：

{
  "object": "list",
  "data": [
    {
      "id": 1287,
      "indicator": "fasting_glucose",
      "value": "5.4 mmol/L",
      "parsed_value": "5.4",
      "parsed_unit": "mmol/L",
      "loinc_code": "1558-6",
      "canonical_name": "Fasting glucose [Mass/volume] in Serum or Plasma",
      "fhir_resource_id": "8f3c9a1e-...",
      "time": "2026-06-16T07:30:00+00",
      "end_time": null,
      "source": "api",
      "comment": ""
    }
  ],
  "has_more": false,
  "subject": "alice"
}

字段	说明
`data`	记录数组（至多 `limit` 条）。
`id`	行 id（整数）—— 传给 `DELETE /v1/data?id=` 做行级删除。
`value`	人读读数（字符串）。
`parsed_value` / `parsed_unit`	标准化管线产出的数值 + UCUM 单位（无法解析时为 `null`）。
`loinc_code` / `canonical_name`	确定性 LOINC 解析结果及其展示名（名称未解析时为 `null`）。
`fhir_resource_id`	该记录 FHIR Observation 镜像的 id。
`end_time`	Episode 型记录（睡眠、运动）时段的结束时间；时间点读数为 `null`。
`source` / `comment`	`source` 表示写入通道(`api`、`extract`);你在记录里传的 `source` 自由文本标签会在 `comment` 中返回。
`has_more`	本页打满 `limit` 时为 `true`——用 `offset += limit` 取下一页。
`subject`	记录所属的 Subject（由 `user` 解析）。

擦除记录

DELETE /v1/data?user=alice&indicator=fasting_glucose
Authorization: Bearer mb_live_*

硬删除该 Subject 的记录 —— 被遗忘权语义（行被物理移除，而非打标）。三种范围，由窄到宽：

Query	范围
`id`	恰好一行 —— 即 `GET /v1/data` 返回的整数 id。优先于 `indicator`。
`indicator`	单个指标（子串匹配，与 GET 过滤一致）。
（都不传）	该 Subject 的全部记录。

DELETE /v1/data?user=alice&id=1287

{ "status": "ok", "deleted": 1, "subject": "alice" }

如需擦除某个 Subject 的一切（记录 + 文件 + 对话 + 身份映射），使用 DELETE /v1/subjects/{user} —— 见合规。

用完即弃的数据

没有 retention: "none" —— 写入存储却要求不存储是自相矛盾的，该值与其它非枚举值一样被拒绝。两种干净的替代模式：

零副作用的 dry-run 分析 —— POST /v1/extract 用 store=false（默认）：拿到标准化结果，什么都不写。
短生命周期工作数据 —— 以 retention: "1h" 写入，或 retention: "session" + 一个用完即删的 session_id。

​写入记录

​Episode 型（睡眠、运动）

​读取记录

​擦除记录

​用完即弃的数据

写入记录

Episode 型（睡眠、运动）

读取记录

擦除记录

用完即弃的数据