---
title: "Health Chat API"
description: "Use the ScholarXIV health assistant through one API, with the same profile, tools, files, and conversations as /health."
canonical_url: "https://scholarxiv.com/developers/docs/health-api"
markdown_url: "https://scholarxiv.com/developers/docs/health-api.md"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

# Health Chat API
URL: /developers/docs/health-api
LLM index: /llms.txt
Description: Use the ScholarXIV health assistant through one API, with the same profile, tools, files, and conversations as /health.
Related: agent-api, papers-api/authentication, papers-api/limits, mcp/tools

# Health Chat API

`POST /api/v1/health/chat` runs the same assistant as the website's `/health` chat: the same system prompt, health profile, medical tools, model routing, continuation, and conversation storage. Health is available on Go and above. The profile, medications, and literature tools stay on the server.

Use the [Agent API](/developers/docs/agent-api) for the research workspace. This endpoint answers health questions with the caller's health profile and the medical literature and medication tools.

## Ask a question

```bash
curl https://scholarxiv.com/api/v1/health/chat \
  -H "Authorization: Bearer sxv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message":"What does the research say about taking ibuprofen with metformin?","model":"auto"}'
```

The default response matches the Agent API JSON shape: `chat_id`, `text`, `model`, `usage`, `finish_reason`, and the full assistant `message`, including tool parts. `stream: true` is the same AI SDK UI-message event stream, with `X-Chat-Id` available before the first token.

Send `chat_id` to continue. The service reloads stored history. Do not send a transcript, a system prompt, or a user id.

## Request fields

| Field | Type | Meaning |
|---|---|---|
| `message` | string, required | Nonblank question, up to 64,000 characters. |
| `chat_id` | string | Owned health conversation ID. Omit to create one. A research chat ID is rejected. |
| `stream` | boolean | Default `false`. |
| `model` | string | An entitled health model or `auto`. Defaults to the plan's health model, which can read long context, images, and PDFs. |
| `attachment_ids` | string[] | Up to five ready files owned by the caller, uploaded with `scope: "health"`. |
| `reply_contexts` | object[] | Up to ten excerpts being replied to: `{ "text", "source_message_id"? }`. |

`GET /api/v1/health/chat/{chatid}` returns the stored conversation. `GET /api/v1/models?surface=health` lists the models this plan can run.

## Profile

The assistant reads the caller's health profile on every turn, the same way `/health` does.

```bash
curl https://scholarxiv.com/api/v1/health/profile \
  -H "Authorization: Bearer sxv_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"consentGiven":true,"conditions":["Type 2 diabetes"],"medications":["metformin"]}'
```

`consentGiven: true` is required. `GET /api/v1/health/profile` reads it. `DELETE /api/v1/health/profile?confirm=delete` removes the profile, trackers, and lab panels.

## Files, dictation, and conversations

Use the shared harness with the health surface:

| Action | Request |
|---|---|
| Upload a lab report or photo | `POST /api/v1/uploads/presign` with `"scope": "health"`, PUT the bytes, then `POST /api/v1/uploads/complete` |
| Dictate | `POST /api/v1/transcribe` with multipart `audio` and `provider` (`addis` or `elevenlabs`), then send the text as `message` |
| List health chats | `GET /api/v1/chats?surface=health` |
| Rename, pin, archive | `PATCH /api/v1/chats/{chatid}` |
| Delete | `DELETE /api/v1/chats/{chatid}` also deletes the health messages |
| Share | `POST /api/v1/chats/{chatid}/share` |

The server selects the same tools as `/health`, including medical literature search and medication reference lookups. A client does not implement those tools. Invalid requests return 400, invalid keys 401, a plan without health or an unavailable model 403, an unknown chat 404, attachment conflicts 409, an oversized context 413, rate limits 429, and assistant failures 502.

The MCP `health_chat` tool calls this same service and returns a completed answer. Website and mobile clients can keep using session `POST /api/health/chat`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).