---
title: "Quickstart"
description: "Authenticate, ask a health question, and continue the conversation."
canonical_url: "https://scholarxiv.com/developers/docs/health-api/quickstart"
markdown_url: "https://scholarxiv.com/developers/docs/health-api/quickstart.md"
---

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

# Quickstart
URL: /developers/docs/health-api/quickstart
LLM index: /llms.txt
Description: Authenticate, ask a health question, and continue the conversation.
Related: health-api, health-api/quickstart

# Quickstart

Use an API key from the [Developer Dashboard](/developers/dashboard/apikeys). Send `Authorization: Bearer sxv_...` or `x-api-key: sxv_...`. Health requires Go or above. Keep keys on your backend.

## 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`, `run_id`, `text`, `model`, `usage`, `metrics`, `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` and `X-Run-Id` available before the first token.

Every health turn is a [run](/developers/docs/agent-api/runs), exactly as on the Agent API: send `background: true` to get `202` and read the answer from `GET /api/v1/runs/{run_id}`, resume a dropped stream from its last event id, and send an `Idempotency-Key` header so a retry returns the same run instead of asking twice. One turn runs per conversation at a time; a second message meanwhile returns `409 run_in_progress`.

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"? }`.                                                                                                  |
| `background`      | boolean          | Default `false`. Return `202` with the run at once; cannot be combined with `stream: true`.                                                                               |
| `max_steps`       | integer          | 1–5. Lowers the tool-step budget for this turn.                                                                                                                           |
| `tools`           | object           | `allow` / `deny` lists of health tool names (`searchMedicalLiterature`, `resolveMedications`, `getMedicationReference`, `getDrugLabelInteractions`), and `memory: false`. |
| `response_format` | object           | A JSON Schema to also return the answer as a matching `output` object — see [Structured output](/developers/docs/agent-api/tools#structured-output).                      |
| `metadata`        | object           | Up to 16 string tags stored on the run and its usage row.                                                                                                                 |

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

## 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).
