Files - Mirobody

Upload a health document and Mirobody parses it into the Subject’s store. PDFs and images go through OCR; Excel / CSV are parsed structurally into health records. The chat agent then reads uploaded files automatically when it answers.

Uploads are capped at 100 MB per file — larger requests return 413. For big exports or realtime streams, use the WebSocket upload path.

Upload & parse

POST /v1/files
Authorization: Bearer mb_live_*
Content-Type:  multipart/form-data

Field	Description
`file`	The document (PDF / image / Excel / CSV).
`user`	Subject the file belongs to. Optional — omitting it falls back to your account’s `default` Subject, so always pass it for per-end-user isolation.
`retention`	Optional here (unlike `POST /v1/data`, where it’s required). Same values as Data retention.
`session_id`	Optional; scopes `retention=session` uploads to a session.

curl https://mirobody-api.thetahealth.ai/v1/files \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -F "user=alice" \
  -F "file=@checkup_2026.pdf"

Response:

{
  "object": "file",
  "id": "AUmIn_R-Ddg.../b/bM--fG29X....csv",
  "filename": "checkup_2026.pdf",
  "bytes": 20544,
  "status": "processed",
  "created_at": 1782924296,
  "subject": "alice"
}

The file’s identifier is id (a slash-containing key) — use it as {file_key} in the fetch and list calls below. created_at on the upload response is epoch seconds. The upload response does not include an indicator count or an abstract.

Images and PDFs are OCR’d to text the agent can read; structured-indicator extraction is asynchronous / best-effort. For guaranteed structured data, use POST /v1/data or upload a CSV / Excel file.

List files

GET /v1/files?user=alice
Authorization: Bearer mb_live_*

{
  "object": "list",
  "data": [
    {
      "object": "file",
      "id": "AUmIn_R-Ddg.../b/bM--fG29X....csv",
      "file_key": "AUmIn_R-Ddg.../b/bM--fG29X....csv",
      "filename": "checkup_2026.pdf",
      "file_type": "application/pdf",
      "bytes": 20544,
      "created_at": 1782924296
    }
  ],
  "subject": "alice"
}

data holds the files; subject echoes the Subject. Each item exposes both id and file_key (identical values). created_at is epoch seconds, matching the upload response.

Fetch parsed text

GET /v1/files/{file_key}?user=alice
Authorization: Bearer mb_live_*

Returns the parsed text for one file — the same content the agent reads:

{
  "object": "file",
  "id": "AUmIn_R-Ddg.../b/bM--fG29X....csv",
  "filename": "checkup_2026.pdf",
  "extracted_text": "date,indicator,value\n2026-06-16,fasting_glucose,5.4\n",
  "abstract": "",
  "subject": "alice"
}

abstract may be empty (it isn’t generated for every file type).

WebSocket upload

For large exports or realtime capture, wss://…/v1/files/stream uploads over one socket with chunking and progress. Auth rides the query string (browsers can’t set WebSocket headers):

wss://mirobody-api.thetahealth.ai/v1/files/stream?key=mb_live_...&user=alice&retention=permanent

Frame sequence (all JSON text frames):

Server → you: {"type": "connection_established"} — send nothing before this.
You → server: {"type": "upload_start", "messageId": "<batch-id>", "files": [{"filename", "contentType", "size"}]} — one messageId for the whole batch.
You → server, per 256 KB chunk: {"type": "upload_chunk", "messageId", "filename", "chunk": "<base64>", "chunkIndex", "totalChunks"}.
You → server: {"type": "upload_end", "messageId"} → server replies upload_end_response when every file is stored + parsed.

Same 100 MB per-file cap, same Subject isolation, and the stored files are identical to a POST /v1/files upload — list them with GET /v1/files.

Delete a file

DELETE /v1/files/{file_key}?user=alice
Authorization: Bearer mb_live_*

Removes the file from the API surface immediately (404 if it isn’t the Subject’s file or is already deleted):

{ "object": "file", "id": "AUmIn_R-Ddg.../b/bM--fG29X....csv", "deleted": true, "subject": "alice" }

Time-bounded uploads are also removed automatically by retention expiry. To erase everything about a Subject at once, use DELETE /v1/subjects/{user} — see Compliance.

​Upload & parse

​List files

​Fetch parsed text

​WebSocket upload

​Delete a file

Upload & parse

List files

Fetch parsed text

WebSocket upload

Delete a file