Answers API (Chat Completions)

Endpoint

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

The Answers API is a closed, grounded completion: one question in, one evidence-backed answer out. The platform’s agent gathers the Subject’s real health data with server-side tools (you can’t add or remove them here), then composes a single clean answer with a traceable tool trace. Set stream: true for SSE. It is deliberately closed — no client tools, no response formatting, no multi-turn state. That makes it trivial to embed: call it directly, or wrap it as one tool inside your own agent. If you need client-side tools, stored conversations, or previous_response_id chaining, use the Agent API (POST /v1/responses). All /v1 endpoints share one base URL — pick your contracted cluster:

https://mirobody-api.thetahealth.ai/v1

China-region deployments use https://mirobody-api.thetahealth.cn/v1. See Regions for the full host matrix.

Quickstart

curl https://mirobody-api.thetahealth.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "mirobody-flash",
        "messages": [{"role": "user", "content": "How is my fasting glucose trending?"}],
        "user": "alice"
      }'

from openai import OpenAI

client = OpenAI(api_key="mb_live_...", base_url="https://mirobody-api.thetahealth.ai/v1")

resp = client.chat.completions.create(
    model="mirobody-flash",
    messages=[{"role": "user", "content": "How is my fasting glucose trending?"}],
    user="alice",                                 # tenant-isolation key (a Subject)
)
print(resp.choices[0].message.content)
# resp.choices[0].message.reasoning_content      # deep-thinking (CoT) detail (may be empty)
# resp.choices[0].message.tool_steps             # server tool trace: {id, name, arguments, result}

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MIROBODY_API_KEY,
  baseURL: "https://mirobody-api.thetahealth.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "mirobody-flash",
  messages: [{ role: "user", content: "How is my fasting glucose trending?" }],
  user: "alice",
});
console.log(resp.choices[0].message.content);

Request body

Field	Type	Description
`model`	string	`mirobody-flash` (default) or `mirobody-expert`. See Models.
`messages`	array	OpenAI `{role, content}`. The surface is stateless — send the full history each call; a `system` message shapes tone/format (see System prompts).
`stream`	bool	`true` → SSE stream of `chat.completion.chunk` frames.
`user`	string	Tenant-isolation key → a Subject. Pass each end-user’s stable id. See multi-tenancy.
`retention`	string	Mirobody extension, accepted for parity with the data plane. Data lifetimes are governed where data is written — see Data and the retention model.
`session_id`	string	Mirobody extension. Tags the call for session-scoped cleanup. For real multi-turn state, use the Agent API.

The user field is the tenant-isolation key. The backend maps (your account, user) to an internal Subject; each user you pass is fully isolated from the others. Pass each end-user’s stable id and their data never crosses over. Omit it and the call falls back to your account’s default Subject. Subjects are invisible to the Mirobody web app and to other developers. The user value is normalized (trimmed + lowercased) before mapping, so Alice and alice resolve to the SAME Subject — pass a stable, canonical id.

Unsupported parameters

This surface is a closed grounded completion — tools run server-side only, and the answer is free-form text. Parameters that contradict that are explicitly rejected with 400 (code: unsupported_parameter, param names the offender) rather than silently swallowed:

Parameter	Result
`tools`, `functions`	`400 unsupported_parameter` — bring your own tools via the Agent API
`tool_choice`, `function_call`	`400 unsupported_parameter`
`response_format`	`400 unsupported_parameter` — structured output is not available on this surface
`n` > 1	`400 unsupported_parameter` — always a single choice

Sampling parameters are accepted but ignored (industry norm for agent-backed surfaces): max_tokens doesn’t cap output; temperature, top_p, stop, and seed have no effect. The response always contains a single choice.

Response

message.content carries one clean final answer. The gather phase (thinking + tool calls) is surfaced in separate channels, so the answer itself is never polluted by tool narration.

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1783741077,
  "model": "mirobody-flash",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "Your fasting glucose has trended down ~8% over the last 30 days ...",
      "reasoning_content": "",                                            // deep-thinking (CoT); may be empty
      "tool_steps": [                                                     // server tool trace, ordered
        { "id": "call_abc", "name": "query_health_data",
          "arguments": { "query": "fasting glucose last 90 days" },
          "result": "{...}" }
      ]
    }
  }],
  "usage": {
    "prompt_tokens": 12,                                                  // YOUR visible input only
    "completion_tokens": 210,
    "total_tokens": 222,
    "prompt_tokens_details": { "system_tokens": 10096 },                  // platform overhead, not billed to your prompt
    "completion_tokens_details": { "reasoning_tokens": 0 }
  },
  "health_records": [ { "tool": "query_health_data", "data": "..." } ],
  "citations": [ { "tool": "search_medical_literature", "data": "..." } ]
}

Channel	Content
`message.content`	Final answer only (the “reply” channel).
`message.reasoning_content`	The model’s deep-thinking (CoT) detail. May be an empty string when the tier doesn’t emit it.
`message.tool_steps[]`	The server tool trace — each `{id, name, arguments, result}`, merged by `id`. Always returned; there is no opt-in flag and no truncation switch.
`health_records`	Traceable health-data tool outputs the answer used — `{tool, data}` pairs. This is where the explainability lives.
`citations`	Literature-tool outputs (`search_medical_literature` / `get_clinical_trials` / `get_article_by_pmcid`) — `{tool, data}` pairs; empty when no literature was consulted.
`usage`	Token accounting — see below.

reasoning_content and tool_steps are additive channels — clients that only read message.content keep working.

Usage accounting

usage.prompt_tokens reports the input you actually sent (your messages); the platform’s own system prompt and tool schemas are broken out as prompt_tokens_details.system_tokens instead of being blamed on your prompt. completion_tokens_details.reasoning_tokens counts thinking tokens. Counts are summed across every model call of the agent turn.

Streaming

With stream: true, frames arrive in order. The first chunk carries delta.role: "assistant" (OpenAI parity — many clients key message init off it), then tool/thinking deltas, then a single uninterrupted answer stream:

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":""}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"reasoning_content":"<fragment>"}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"tool_steps":[{"id":"call_abc","name":"query_health_data","arguments":{...}}]}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"<answer fragment>"}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}],"health_records":[...],"citations":[...],"usage":{...}}
data: [DONE]

Frames are chat.completion.chunk objects. Merge tool_steps by id (streamed steps carry {id, name, arguments}; full result payloads are available on the non-stream response). The final frame (before [DONE]) carries the top-level health_records / citations and usage. An upstream failure arrives as an SSE {"error": ...} frame before the stream ends. Clients that only read delta.content keep working.

System prompts

A system message sets the tone, persona, format, and language of the answer. Data gathering is platform-controlled — the agent always reads the Subject’s real data — so a system prompt shapes how the answer reads, never whether real data is used.

Built-in tools

Beyond plain tool-calling, the hosted agent can plan multi-step work, delegate subtasks, run sandboxed code for numeric analysis (trends, correlations), and read the Subject’s uploaded files. You don’t invoke any of this — the agent does, against the Subject’s data. The public tool catalog — what GET /api/health reports as tool_names:

query_health_data, summarize_health_data — search and aggregate the Subject’s records
list_clinical_records — list clinical documents / FHIR-backed records
list_family_members — resolve care-circle members the Subject is allowed to query
write_fhir_observation — write a structured FHIR observation
search_medical_literature, get_clinical_trials, get_article_by_pmcid — look up medical evidence (feeds citations)
fetch_url — read a web page

Planning / delegation / code-analysis tools are internal plumbing and not part of the API contract. ask_user appears in GET /api/health’s tool_names (it serves the web app) but is disabled on the /v1 surfaces — an API caller has no widget to answer it. The public set can vary by cluster; GET /api/health reports the live tool_names. Files you upload via /v1/files land in /uploads, and the agent reads them automatically. To add your own tools, use the Agent API’s function calling — this surface intentionally has no tool injection.

Charts (vis-chart)

When the answer involves a trend / comparison / distribution, it may embed a fenced ```vis-chart block of pure-data JSON ({type, title, axisXTitle, axisYTitle, data}). Rendering is the client’s job — the API only returns the data spec. Detect the fenced block and render it (line / area / bar / pie).

​Endpoint

​Quickstart

​Request body

​Unsupported parameters

​Response

​Usage accounting

​Streaming

​System prompts

​Built-in tools

​Charts (vis-chart)

Endpoint

Quickstart

Request body

Unsupported parameters

Response

Usage accounting

Streaming

System prompts

Built-in tools

Charts (vis-chart)