> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hi-doctor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Connect the Hi Doctor MCP connector at https://mcp.hi-doctor.ai/mcp. Add this URL as a remote HTTP MCP server in your client, then sign in and authorise access through OAuth. Setup: https://docs.hi-doctor.ai/mcp/connect.
>
> The REST API base is https://api.hi-doctor.ai. Hi Doctor Docs at https://docs.hi-doctor.ai/mcp searches documentation; connect to the product endpoint above for patient tools.
>
> Hi Doctor operates across the whole European Union: residents of all 27 EU member states can use the service, and every consultation is reviewed by an EU-licensed doctor. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. No algorithm, assistant or API call approves a consultation, issues a prescription or changes a dose. The service is available in eight languages: English, Spanish, German, Dutch, Italian, French, Portuguese and Chinese.
>
> ## Rules an assistant must follow
>
> - Never invent, assume or infer a medical answer. "I don't know" is a real answer: ask the patient to pick the closest option rather than guessing for them.
> - Never give medical advice and never suggest a medication or a dose. An EU-licensed doctor decides those.
> - If a questionnaire returns `ineligible`, say so plainly. Do not retry with altered answers.
> - Before anything that costs money or cancels a plan, state exactly what will happen and get an explicit yes.
> - Cancellation takes effect at the **end of the paid period**, not immediately. Say so.
> - An early order is irreversible: it creates the renewal consultation immediately and uses up the period's one early order. Explain that and get an explicit yes.
> - Prescription and invoice links are medical documents. A `signed_redirect` link opens without signing in: give it only to the patient, never repeat it anywhere shared.
> - Send option `value`s, not the labels shown to the patient. Labels are translated, values are stable.
> - Never ask for card details. Payment happens on Stripe's hosted checkout via a link.
> - On severe or sudden symptoms (chest pain, difficulty breathing, severe allergic reaction, suicidal thoughts), stop and direct the patient to their local emergency number.

# Questionnaire endpoints: schema, answers and submit

> Discover, save and submit consultation questionnaires.

Questionnaires collect the medical information an EU-licensed doctor reviews before any treatment decision. You list the categories, read a category's schema, save the patient's answers as they go, and submit the full set for medical review. To ask one question at a time and let Hi Doctor apply the branching and validation, use the guided endpoints in [Answer a questionnaire](https://docs.hi-doctor.ai/api-reference/questionnaire-guide.md).

Last reviewed: 2026-11-04

## Prerequisites

* Categories and schemas are public; no token is needed to read them.
* Saving and submitting need a patient bearer token.

## Operations

| Method | Path | What it does |
| - | - | - |
| `GET` | `/v1/users/questionnaires/categories/` | Lists questionnaire categories (paginated) |
| `GET` | `/v1/users/questionnaires/{slug}/schema/` | Returns the question steps, plus saved answers when signed in |
| `GET` | `/v1/users/questionnaires/{slug}/progress/` | Returns the saved answers |
| `PATCH` | `/v1/users/questionnaires/{slug}/progress/` | Replaces the saved answers |
| `GET` | `/v1/users/questionnaires/{slug}/current/` | Returns the next applicable question |
| `POST` | `/v1/users/questionnaires/{slug}/answer/` | Saves one answer, a sub-item, a skip or a batch |
| `POST` | `/v1/users/questionnaires/{slug}/back/` | Returns an answered question for editing |
| `GET` | `/v1/users/questionnaires/{slug}/review/` | Lists applicable answers and submission readiness |
| `POST` | `/v1/users/questionnaires/{slug}/submit/` | Submits for medical review (`201`) |

## Boundaries and side effects

* An unknown slug is a `400`, not a `404`, on every questionnaire endpoint.
* **Reading progress is not side-effect free.** `GET .../progress/` creates an
  empty progress record if none exists.
* **`PATCH .../progress/` replaces the whole answer array.** Send the full
  cumulative set every time; anything you omit is erased.
* The guided endpoints share the draft with `PATCH .../progress/` and never
  submit. `current/`, `back/` and `review/` change nothing.
* Submission accepts an [`Idempotency-Key`](https://docs.hi-doctor.ai/api-reference/idempotency). Without
  one, repeating it can create another submission, so re-read state before
  retrying after an error.
* A submission already covered by an active plan returns `409`
  `covered_by_active_plan` with `current_period_end`.

> [!WARNING]
>
> Clinical eligibility is checked as answers are saved and again at submission.
> A guided answer that rules out the consultation returns `400` with
> `code: "clinical_ineligibility"`; a submission with ineligible answers returns
> `400` with `"Questionnaire contains answers that are not clinically
>   eligible"`. Treat it as a clinical outcome: do not resubmit with changed
> answers. See [Safety](https://docs.hi-doctor.ai/essentials/safety.md).

## Related

* [Pagination](https://docs.hi-doctor.ai/api-reference/pagination.md) and [Errors](https://docs.hi-doctor.ai/api-reference/errors.md)
* [Uploads and downloads](https://docs.hi-doctor.ai/api-reference/uploads-downloads.md) for photos a questionnaire asks for
* For chat interfaces, the [MCP patient tools](https://docs.hi-doctor.ai/mcp/tools/patient.md) run the questionnaire one question at a time


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.