Mirobody’s hosted API is OpenAI-compatible. Point any OpenAI SDK at the base URL below, pass an mb_live_* key, and call /v1/chat/completions — the agent answers from each end-user’s real, structured health data, with traceable citations. The same engine also runs self-hosted via pip install mirobody or the open-source stack; the hosted API adds managed storage, keys, and billing on top.
You create keys, watch usage, and try an interactive Playground in the developer console. These docs are the API reference.
Base URL
https://mcp.thetahealth.cn/v1
https://test-mcp.thetahealth.cn/v1
mb_live_* key — see Authentication. A global region is coming soon; see Regions.
Authentication
| Surface | Scheme | How to get it |
|---|
/v1/* (the API) | Authorization: Bearer mb_live_* | Create a key in the console → API Keys. The secret is shown once. |
/api/console/* (console) | Session JWT (login) | Email-code or WeChat login in the console. |
/v1 keys are not JWTs — they’re long-lived API keys scoped to your account. Never ship them in client-side code.
OpenAI compatibility
Standard OpenAI fields work as-is; Mirobody extensions ride along in extra_body (Python SDK) or as plain top-level JSON (curl/fetch).
| Fields |
|---|
| Standard | model, messages, stream, user |
| Mirobody extensions | retention, session_id, health_context, mcp_servers, include_tool_steps |
| Response | choices[0].message.content (+ reasoning_content, tool_steps), usage, plus top-level health_records / citations |
Sampling parameters are accepted for compatibility, but the agent runs its own generation. max_tokens is accepted but not enforced — the agent controls output length. temperature, top_p, stop, and seed are accepted but ignored. n must be 1; any other value returns 400.
Multi-tenancy: the user field
Every request carries a user string — 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 as user and their data never crosses over. Omit it and the call falls back to your account’s default Subject. Subjects are not consumer accounts — they’re invisible to the Mirobody app and to other developers.
Data retention
Anything you supply (structured records, uploaded files, inline health_context) carries a retention that decides how long it’s kept:
retention | Meaning | Lifetime |
|---|
permanent (default) | Kept until explicitly deleted | Permanent |
session | Bound to session_id, dropped when the session ends | ≤ 24h, or DELETE /v1/sessions/{id} |
1d | Auto-deleted within a day | ≤ 24h |
6h | Auto-deleted 6 hours after write | ≤ 6h |
2h | Auto-deleted 2 hours after write | ≤ 2h |
1h | Auto-deleted 1 hour after write | ≤ 1h |
none | Used for this request only, never persisted | Deleted in finally |
permanent | 1h | 2h | 6h | 1d | session | none. Any time-bounded grain is hard-capped at ≤ 24h.
none is meant for inline health_context (use-and-forget). On POST /v1/data it is rejected with HTTP 400 (writing to the store but asking not to store is contradictory) — to use-and-forget structured data, attach it as health_context with retention=none on POST /v1/chat/completions instead. The agent only ever reads the Subject’s currently-unexpired data.
Citations
Answers carry traceable references to the health records they used (health_records / citations), so results are explainable and checkable — not “sounds plausible,” but “this conclusion came from that record of yours.”
Errors use the OpenAI-style envelope:
{
"error": {
"message": "X-... is required for this endpoint.",
"type": "invalid_request_error",
"code": "invalid_request"
}
}
| HTTP | When |
|---|
400 | Malformed request / missing required field |
401 | Missing or invalid mb_live_* key |
404 | Unknown resource (e.g. file_key / session_id) |
429 | Rate limit — see Rate Limits |
500 | internal_error — an unexpected server-side failure |
502 | Upstream agent error — transient; retry with backoff |
Endpoints at a glance
| Method | Path | Purpose |
|---|
GET | /v1/models | List capability tiers (mirobody-flash / mirobody-expert) |
POST | /v1/chat/completions | OpenAI-compatible health chat (stream, health_context, mcp_servers) |
POST · GET | /v1/data | Write / read structured records |
POST · GET | /v1/files | Upload & parse files (OCR / Excel), list, fetch parsed text |
DELETE | /v1/sessions/{id} | End a session, purge its session data |
GET·POST·DELETE | /api/console/keys | Manage API keys (JWT) |
GET | /api/console/usage | Usage: requests / tokens / cost (JWT) |
