Quickstart - Mirobody

This first run uses curl and two sample readings. You will write them, confirm that they resolve to the same LOINC code, and ask a question about them. Allow about 10 minutes. The example keeps the readings for one hour; set an appropriate retention period for real data.

Preparation

Create a mb_live_* key in the console for the same region you will call: Global or China. Open API Keys and copy the secret when it appears; it is shown once. Set the matching API base URL and key in your shell. This example selects Global; for a China account, use the commented China line instead:

export MIROBODY_API_BASE="https://api.mirobody.ai/v1"   # Global
# export MIROBODY_API_BASE="https://api.mirobody.cn/v1" # China: use this instead
export MIROBODY_API_KEY="mb_live_..."

All /v1 endpoints share one base URL — pick the cluster your account uses:

https://api.mirobody.ai/v1   # Global
https://api.mirobody.cn/v1   # China

These are the Cloud clusters. A self-hosted deployment does not expose /v1 — it serves its own /api/* routes and an /mcp endpoint, described in the Self-Host Mirobody. Japan and EU clusters are in preparation — see Regions. Model providers and pricing can differ by region, so read GET /v1/models from the cluster you call.

Run the example

① Collect: write two sample readings

Health data arrives in four shapes, and each has exactly one endpoint to write it through:

Data shape	Typical source	How it goes in	Endpoint
Structured records	Devices and wearables above all (you own the integration — write daily aggregates), plus manual entries	Structured records	`POST /v1/data` — pre-aggregate high-frequency samples; episodes (sleep, workouts) carry `time` + `end_time`. See the device-data cookbook.
Files / photos	Lab reports, checkup PDFs, phone photos	File upload	`POST /v1/files` — stores the original, extracts its text, and pulls out standardized readings automatically. `POST /v1/standardize` runs the same extraction synchronously — for example as a dry-run preview.
Narrative with readings	”headache all day, temperature was 38.2 °C”, dictated notes	Narrative text	`POST /v1/standardize` — the quantifiable readings are extracted; the narrative around them is dropped.
Purely subjective journal	”dizzy and a headache all afternoon”, mood notes	Single-turn agent call	`POST /v1/responses` with `store: true` — readings and durable memories are extracted from the entry. See the Journaling recipe.

Mirobody stores source data, standardizes structured readings, and makes both available to AI. You decide how data is collected and prepared before it reaches the API.Write structured readings with POST /v1/data. retention is required. Keep the same user value in every step so all calls address the same Subject.

curl "$MIROBODY_API_BASE/data" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "user": "docs-demo",
        "retention": "1h",
        "records": [
          {"indicator": "fasting_glucose", "value": 97, "unit": "mg/dL", "time": "2026-06-16T07:30:00Z"},
          {"indicator": "FBG",             "value": 92, "unit": "mg/dL", "time": "2026-06-17T07:25:00Z"}
        ]
      }'

Expect a JSON response with "status": "ok", "ingested": 2, and "subject": "docs-demo". standardized tells you how many readings received a LOINC code. If you repeat this write, you create more rows: writes are not idempotent.user is the tenant-isolation key. Use a stable, distinct id for each end-user in your application.

② Translate: it comes back coded

Note the two spellings above — fasting_glucose and FBG. Read the data back and both rows carry the same LOINC code, a canonical name, and UCUM-parsed values:

curl "$MIROBODY_API_BASE/data?user=docs-demo&limit=10" \
  -H "Authorization: Bearer $MIROBODY_API_KEY"

{
  "object": "list",
  "data": [
    {
      "indicator": "FBG",
      "value": "92",
      "parsed_value": "92",
      "parsed_unit": "mg/dL",
      "loinc_code": "1558-6",
      "canonical_name": "Fasting glucose [Mass/volume] in Serum or Plasma",
      "time": "2026-06-17T07:25:00+00",
      "source": "api",
      "comment": ""
    },
    {
      "indicator": "fasting_glucose",
      "value": "97",
      "parsed_value": "97",
      "parsed_unit": "mg/dL",
      "loinc_code": "1558-6",
      "canonical_name": "Fasting glucose [Mass/volume] in Serum or Plasma",
      "time": "2026-06-16T07:30:00+00",
      "source": "api",
      "comment": ""
    }
  ],
  "has_more": false,
  "subject": "docs-demo"
}

On a fresh Subject, the response should include both names with the same loinc_code; IDs and other fields may vary. value is the original number as a string, and the parsed unit is separate. That’s the standardization pipeline: deterministic name→LOINC (no LLM code-guessing) + UCUM on every structured-record write.

③ Agent: get a grounded answer

Call the Answers API with the same user. It can consult the rows you just wrote, including the one named FBG:

curl "$MIROBODY_API_BASE/chat/completions" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "mirobody-flash",
        "user": "docs-demo",
        "messages": [{"role": "user", "content": "What fasting glucose readings did I add?"}]
      }'

Read the answer in choices[0].message.content. health_records and message.tool_steps show which records and server tools were used; their content varies by run. For your own tool calls or conversation state, continue with the Agent API and SDK examples. Pass the same Subject when using an agent SDK; otherwise it reads your account’s default Subject.

If a call fails

For 401, check that the key and MIROBODY_API_BASE belong to the same region, then check the bearer header. For 400, read error.code and error.param in the error reference. For 429, follow Rate Limits & Quota; a rate limit and an exhausted quota need different responses.

Other data sources

For a lab report, upload a PDF, photo or spreadsheet. For a synchronous preview of extracted readings, use POST /v1/standardize with a file or an uploaded file_key. For device readings at scale, continue with Structured Records. These paths share the same user isolation rule.

The console Playground

The console Playground follows the same flow: ① Collect data → ② Auto-standardize → ③ Agent or Answers. Upload a file, inspect the extracted text or standardized records, and run either API without writing code. Open the console for your account’s region; usage is in its sidebar.

Global Playground

For keys created at platform.mirobody.ai.

China Playground

For keys created at platform.mirobody.cn.

Next steps

Choose your API

Answers vs Agent — closed completion or full agent.

Agent API

Client tools, stored conversations, streaming events.

Standardization

OCR → extraction → LOINC → UCUM, explained.

SDK Examples

curl / Python / Node / openai-agents, end to end.

​Preparation

​Run the example

​If a call fails

​Other data sources

​The console Playground