Answers API (Chat Completions)

Before copying a curl example, choose your Cloud region. For authenticated calls, it must be the same region as your key. The examples below use MIROBODY_API_BASE:

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

For SDK examples with a literal Global URL, use the matching China URL when your account is in China. See Regions.

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 returns one clean answer plus a traceable record of the tools it used. Set stream: true for SSE. It is deliberately closed — no client tools, no response formatting, no multi-turn state. That makes it easy 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 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.

Quickstart

Set the key for the same region as MIROBODY_API_BASE before running any example:

export MIROBODY_API_KEY="mb_live_..."

curl "$MIROBODY_API_BASE/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"
      }'

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MIROBODY_API_KEY"], base_url=os.environ["MIROBODY_API_BASE"])

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      # provider-supplied reasoning text (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: process.env.MIROBODY_API_BASE,
});

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.

The user field is the tenant-isolation key. The backend maps (your account, user) to an internal Subject, and Subjects are fully isolated from one another — pass each end-user’s stable id and no user ever sees another’s data. 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 value is normalized (trimmed + lowercased) before mapping, so Alice and alice resolve to the same Subject. Pass a stable, canonical id.

retention and session_id are not fields on this stateless surface. Set retention when writing data, files, or readings stored by /v1/standardize. For server-side conversation state, use the Agent API.

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.

reasoning_effort is honored ("low" | "medium" | "high"): it maps to the underlying model’s extended-thinking / reasoning budget. The reasoning streams as delta.reasoning_content and is included as message.reasoning_content in the non-stream response; usage.completion_tokens_details.reasoning_tokens counts it. Omit it for the model’s default; models without a thinking mode ignore it.

Response

message.content carries one clean final answer. Optional provider reasoning text and server tool calls use separate channels, so the answer itself is not mixed with 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": "",                                            // provider-supplied reasoning text; 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 },                  // reported separately from visible prompt_tokens
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "billed_tokens": { "input": 20391, "output": 841, "total": 21232 }    // the actual token total you're metered on
  },
  "health_records": [ { "tool": "query_health_data", "data": "..." } ],
  "citations": [ { "tool": "search_medical_evidence", "data": "..." } ]
}

Channel	Content
`message.content`	Final answer only (the “reply” channel).
`message.reasoning_content`	Provider-supplied reasoning text. It may be empty and is not a guarantee of complete internal reasoning.
`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`	External-evidence outputs (`search_medical_evidence` / `read_source`) — `{tool, data}` pairs; empty when no evidence 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 system prompt and tool schemas are reported separately in prompt_tokens_details.system_tokens. completion_tokens_details.reasoning_tokens reports provider reasoning tokens. Counts are summed across every model call in the agent turn. usage.billed_tokens is the actual token total you’re metered on. Multiplying it by the catalog’s standard input/output rates gives a cost estimate; prompt-cache discounts can make actual metered cost lower.

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 optional reasoning/tool 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]

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. Server-tool availability and Subject scoping remain platform-controlled; the prompt cannot grant access to another Subject or add tools.

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 tools the hosted agent can call:

query_health_data — search and aggregate the Subject’s records
list_family_members — resolve care-circle members the Subject is allowed to query
search_medical_evidence — search literature, guidelines/consensus, and registered trials (feeds citations)
read_source — read one result by its returned ref; arbitrary URL fetching is not supported

The /v1 agent’s main loop is read-only. Health facts mentioned in stored conversations are extracted automatically (see State & memory), not written by a tool during the answer. Planning, delegation, and code-analysis tools are internal and not part of the API contract. ask_user serves the web app but is disabled on the /v1 surfaces because an API caller has no widget to answer it. Files uploaded through /v1/files become readable to the agent once processed. 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)

​See also

Endpoint

Quickstart

Request body

Unsupported parameters

Response

Usage accounting

Streaming

System prompts

Built-in tools

Charts (vis-chart)

See also