> ## 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. # Send questionnaire answers > Merges one answer, one grid or follow-up item, an explicit skip of an optional question, or an atomic `answers` batch into the saved draft, then returns the next item. Values use the same shape and clinical, required-field and upload-ownership validation as submit. A full question answer must leave every required field of that question populated, including active follow-ups. An invalid batch saves nothing. When an answer closes a branch, the answers that no longer apply are removed and listed in `dropped_question_keys` and `dropped_option_inputs`. Send `expected_revision` from the last response to reject a stale write with 409. This endpoint never submits the questionnaire. ### Access, effects and retries **Ownership:** The signed-in patient's own draft for this questionnaire category and active version. **Prerequisites:** An authenticated patient account is required. with a bearer JWT; the category must be enabled for the account brand. JSON object body. **Effects:** Writes the draft shared with PATCH progress; clears completion and submitted_at; prunes answers made inapplicable. Never submits. **Retries:** Send expected_revision. A 409 stale_revision returns the current revision: re-read current or review, then retry. Unchanged data keeps the same revision, so repeating an identical answer is harmless. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/users/questionnaires/{slug}/answer/ openapi: 3.0.3 info: title: Hi Doctor API version: 1.0.1 description: >- The patient-facing Hi Doctor API supports account management, consultation questionnaires, medical documents, messages and billing. Sign-in requires X-Brand-Slug: hi-doctor; authenticated requests use Authorization: Bearer with a JWT access token. See https://docs.hi-doctor.ai/api-reference/introduction for integration guides. contact: name: Hi Doctor email: hello@hi-doctor.ai url: https://docs.hi-doctor.ai servers: - url: https://api.hi-doctor.ai description: Production security: [] tags: - name: Account description: Register, verify, authenticate and manage the signed-in account. - name: Questionnaires description: Discover, save and submit consultation questionnaires. - name: Consultations description: Read consultation state and manage consultation photographs. - name: Prescriptions description: Retrieve issued prescription documents and request reissue. - name: Messages description: Read and send messages to the medical team, and download attachments. - name: Billing description: >- Create checkout, manage subscriptions and retrieve payments/invoices/credit notes. - name: Records description: Read orders and manage patient health documents. - name: Safety reports description: Submit and read suspected side-effect reports; no automated diagnosis. - name: Progress description: Record and review eligible weight-loss progress. - name: Referrals description: Read the signed-in account's referral summary and referral activity. paths: /v1/users/questionnaires/{slug}/answer/: post: tags: - Questionnaires summary: Send questionnaire answers description: >- Merges one answer, one grid or follow-up item, an explicit skip of an optional question, or an atomic `answers` batch into the saved draft, then returns the next item. Values use the same shape and clinical, required-field and upload-ownership validation as submit. A full question answer must leave every required field of that question populated, including active follow-ups. An invalid batch saves nothing. When an answer closes a branch, the answers that no longer apply are removed and listed in `dropped_question_keys` and `dropped_option_inputs`. Send `expected_revision` from the last response to reject a stale write with 409. This endpoint never submits the questionnaire. ### Access, effects and retries **Ownership:** The signed-in patient's own draft for this questionnaire category and active version. **Prerequisites:** An authenticated patient account is required. with a bearer JWT; the category must be enabled for the account brand. JSON object body. **Effects:** Writes the draft shared with PATCH progress; clears completion and submitted_at; prunes answers made inapplicable. Never submits. **Retries:** Send expected_revision. A 409 stale_revision returns the current revision: re-read current or review, then retry. Unchanged data keeps the same revision, so repeating an identical answer is harmless. operationId: questionnaire_guided_answer parameters: - in: path name: slug schema: type: string required: true description: Questionnaire category slug returned by the categories endpoint. example: weight-loss - in: query name: locale required: false schema: type: string enum: - en - es description: >- Presentation language. The query parameter wins over a body locale; otherwise the account locale is used, with English as the fallback. example: en requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GuidedAnswerRequest' examples: example-1: summary: Illustrative request example value: question_key: weight_loss-01-country value: ESP expected_revision: r-8f3c2a91 example-2: summary: Illustrative request example value: answers: - question_key: weight_loss-01-country value: ESP - question_key: weight_loss-02-gender value: male example-3: summary: Illustrative request example value: question_key: weight_loss-allergies skip: true example-4: summary: Illustrative request example value: question_key: mood-grid values_key: interest value: interest: 0 example-5: summary: Illustrative request example value: question_key: weight_loss-currentmedications option_input_key: other option_inputs: other: Details entered by the patient responses: '200': description: The next applicable item, progress and the current revision. content: application/json: schema: $ref: '#/components/schemas/GuidedFlow' examples: example-1: summary: Illustrative response example value: question: question_key: weight_loss-02-gender type: radio kind: single_choice title: What is your biological sex? question_title: What is your biological sex? help: '' options: - value: male label: Male - value: female label: Female constraints: required: true fields: [] sections: [] conditional_fields: {} saved_answer: null complete: false revision: r-8f3c2a91 status: in_progress category_title: Weight loss answered_count: 1 applicable_total: 13 progress: answered: 1 total_applicable: 13 percent: 7.7 reusable_prefill: null dropped_question_keys: [] dropped_option_inputs: [] example-2: summary: Illustrative response example value: question: question_key: weight_loss-02-gender type: radio kind: single_choice title: What is your biological sex? question_title: What is your biological sex? help: '' options: - value: male label: Male - value: female label: Female constraints: required: true fields: [] sections: [] conditional_fields: {} saved_answer: null complete: false revision: r-8f3c2a91 status: in_progress category_title: Weight loss answered_count: 1 applicable_total: 13 progress: answered: 1 total_applicable: 13 percent: 7.7 reusable_prefill: null dropped_question_keys: - weight_loss-previous-medication-dose-wegovy dropped_option_inputs: - question_key: weight_loss-currentmedications option_input_keys: - other '400': description: >- Validation failed. `errors` maps the request field to a list of `{code, message}` objects; answer values are never echoed. An unknown category slug returns `detail` instead. content: application/json: schema: type: object description: >- Guided validation errors use `errors`; an unknown questionnaire category uses `detail`. properties: errors: type: object additionalProperties: type: array items: type: object additionalProperties: {} description: >- Request or question field mapped to a list of {code, message} objects. Answer values are never echoed. detail: type: string description: >- Reason the questionnaire could not be loaded, such as an unknown category slug. examples: example-1: summary: Illustrative response example value: errors: question_key: - code: unknown_question message: Choose a question from this questionnaire. example-2: summary: Illustrative response example value: detail: 'Unknown questionnaire category: not-a-category' '401': description: >- No bearer token, or a token that is expired or malformed. Re-authenticate; do not retry the same token. content: application/json: schema: type: object description: >- Error envelope emitted by the source branch or DRF validation. `detail`, `error` and `code` depend on the branch; field validation uses lists keyed by request field. additionalProperties: {} examples: example-1: summary: Illustrative response example value: detail: Authentication credentials were not provided. '403': description: >- The signed-in account is not a patient account, or the questionnaire is not enabled for its brand. content: application/json: schema: type: object description: >- Error envelope emitted by the source branch or DRF validation. `detail`, `error` and `code` depend on the branch; field validation uses lists keyed by request field. additionalProperties: {} examples: example-1: summary: Illustrative response example value: detail: You do not have permission to perform this action. example-2: summary: Illustrative response example value: code: category_not_enabled_for_brand '409': description: >- Stale revision: another write changed the draft after the revision you sent. Read current or review and retry with the returned revision. content: application/json: schema: $ref: '#/components/schemas/GuidedConflict' examples: example-1: summary: Illustrative response example value: code: stale_revision message: Progress changed. Fetch current and retry. revision: r-51d0e7b4 '415': description: 'The body is not JSON. Send `Content-Type: application/json`.' content: application/json: schema: type: object description: >- Error envelope emitted by the source branch or DRF validation. `detail`, `error` and `code` depend on the branch; field validation uses lists keyed by request field. additionalProperties: {} examples: example-1: summary: Illustrative response example value: detail: Unsupported media type "text/plain" in request. '429': description: >- Too many requests. Wait before retrying; the response may include Retry-After. content: application/json: schema: type: object description: >- Error envelope emitted by the source branch or DRF validation. `detail`, `error` and `code` depend on the branch; field validation uses lists keyed by request field. additionalProperties: {} examples: example-1: summary: Illustrative response example value: detail: Request was throttled. security: - bearerAuth: [] x-codeSamples: - lang: Shell label: curl source: > set -eu umask 077 # Path values must be URL-encoded; query string excludes the leading question mark. url="${HD_BASE_URL:?Set API origin}/v1/users/questionnaires/${HD_PATH_SLUG:?Set the path fixture}/answer/${HD_QUERY_STRING:+?${HD_QUERY_STRING}}" printf 'X-Brand-Slug: hi-doctor\nAccept: application/json\n' > "${HD_REQUEST_HEADERS_FILE:?Private header file}" printf 'Authorization: Bearer %s\n' "${HD_ACCESS_TOKEN:?Set backend JWT}" >> "$HD_REQUEST_HEADERS_FILE" curl --silent --show-error --max-time 30 --request POST \ --header "@$HD_REQUEST_HEADERS_FILE" \ --dump-header "${HD_HEADERS_FILE:?Private response header file}" \ --output "${HD_RESPONSE_FILE:?Private response file}" \ --write-out '%{http_code}\n%{content_type}\n' \ --header 'Content-Type: application/json' \ --data-binary "@${HD_REQUEST_FILE:?JSON fixture file}" \ "$url" - lang: Python label: requests source: > import os, json from pathlib import Path from urllib.parse import quote import requests os.umask(0o077) url = os.environ["HD_BASE_URL"].rstrip("/") + '/v1/users/questionnaires/{slug}/answer/' url = url.replace('{slug}', quote(os.environ['HD_PATH_SLUG'], safe="")) if os.environ.get("HD_QUERY_STRING"): url += "?" + os.environ["HD_QUERY_STRING"] headers = {"X-Brand-Slug": "hi-doctor", "Accept": 'application/json'} headers["Authorization"] = "Bearer " + os.environ["HD_ACCESS_TOKEN"] kwargs = {} kwargs["json"] = json.loads(Path(os.environ["HD_REQUEST_FILE"]).read_text()) response = requests.request('POST', url, headers=headers, timeout=30, allow_redirects=False, **kwargs) Path(os.environ["HD_RESPONSE_FILE"]).write_bytes(response.content) Path(os.environ["HD_HEADERS_FILE"]).write_text(json.dumps(dict(response.headers))) print(response.status_code) print(response.headers.get("Content-Type", "")) - lang: JavaScript label: fetch source: > import { readFileSync, writeFileSync } from "node:fs"; const env = process.env; let url = env.HD_BASE_URL.replace(/\/$/, "") + "/v1/users/questionnaires/{slug}/answer/"; url = url.replace("{slug}", encodeURIComponent(env.HD_PATH_SLUG)); if (env.HD_QUERY_STRING) url += "?" + env.HD_QUERY_STRING; const headers = { "X-Brand-Slug": "hi-doctor", "Accept": "application/json" }; headers.Authorization = "Bearer " + env.HD_ACCESS_TOKEN; const options = { method: "POST", headers, redirect: "manual", signal: AbortSignal.timeout(30000) }; headers["Content-Type"] = "application/json"; options.body = readFileSync(env.HD_REQUEST_FILE, "utf8"); const response = await fetch(url, options); writeFileSync(env.HD_RESPONSE_FILE, Buffer.from(await response.arrayBuffer()), {mode: 0o600}); writeFileSync(env.HD_HEADERS_FILE, JSON.stringify(Object.fromEntries(response.headers)), {mode: 0o600}); console.log(response.status); console.log(response.headers.get("content-type") ?? ""); components: schemas: GuidedAnswerRequest: type: object properties: question_key: type: string description: Stable question key returned by current or review. value: oneOf: - type: string - type: number - type: boolean - type: array items: {} - type: object additionalProperties: {} description: >- Scalar for a single choice, array for multi-select, field map for input or grid questions, or an owned document UUID for uploads. values: oneOf: - type: string - type: number - type: boolean - type: array items: {} - type: object additionalProperties: {} description: Alias of value. Send only one of value and values. option_inputs: type: object additionalProperties: {} description: Follow-up values keyed by option_input_key. additional_info: type: string description: Optional free-text additional information. skip: type: boolean description: Send true, without values, to skip an optional question explicitly. values_key: type: string description: Select one grid item; value[values_key] is then required. option_input_key: type: string description: >- Select one follow-up item; option_inputs[option_input_key] is then required. answers: type: array items: $ref: '#/components/schemas/GuidedAnswer' description: >- Atomic batch of answers. Send it instead of a single answer; an invalid entry saves nothing. expected_revision: type: string description: Revision from the last response. A stale value returns 409. locale: type: string description: en or es. Other values fall back to English. renewal_origin: type: string description: >- Renewal context; send the same value on every guided call and on submit. renewal_changed: type: boolean description: 'Renewal context: whether the patient reports a change.' treatment_id: type: string description: 'Renewal context: the treatment being renewed.' dosage: type: string description: Renewal context. Dosage eligibility is enforced at submit. consultation_id: type: string format: uuid description: 'Renewal context: the consultation being renewed.' GuidedFlow: type: object properties: question: description: >- Descriptor of the next item to show, or null when nothing is pending. anyOf: - $ref: '#/components/schemas/GuidedQuestion' - enum: - null type: string nullable: true complete: type: boolean description: >- True when every required answer is valid. Matches review.ready_to_submit; an unanswered optional question can still be returned. revision: type: string description: >- Opaque content token for optimistic concurrency. Send it back as expected_revision. status: type: string description: in_progress, or ready_to_submit when complete is true. category_title: type: string description: Localized questionnaire title. answered_count: type: integer description: Applicable items answered or explicitly skipped. applicable_total: type: integer description: >- Items that currently apply, including grid items and active required follow-ups. progress: allOf: - $ref: '#/components/schemas/GuidedProgress' description: Navigation progress; not a measure of clinical validity. reusable_prefill: type: object additionalProperties: {} nullable: true description: >- A previous answer the patient may confirm for this question. It does not count as answered. dropped_question_keys: type: array items: type: string description: Parent answers removed from the draft because a branch closed. dropped_option_inputs: type: array items: $ref: '#/components/schemas/GuidedDroppedInputs' description: Follow-up values removed while their parent answer was kept. moved_back: type: boolean description: True when an answered item was selected (back only). at_start: type: boolean description: >- True when no earlier item precedes the returned question; also true for an empty questionnaire. required: - answered_count - applicable_total - category_title - complete - progress - question - revision - status GuidedConflict: type: object properties: code: type: string description: stale_revision. message: type: string description: Human-readable explanation. revision: type: string description: The current revision to retry with. required: - code - message - revision GuidedAnswer: type: object properties: question_key: type: string description: Stable question key returned by current or review. value: oneOf: - type: string - type: number - type: boolean - type: array items: {} - type: object additionalProperties: {} description: >- Scalar for a single choice, array for multi-select, field map for input or grid questions, or an owned document UUID for uploads. values: oneOf: - type: string - type: number - type: boolean - type: array items: {} - type: object additionalProperties: {} description: Alias of value. Send only one of value and values. option_inputs: type: object additionalProperties: {} description: Follow-up values keyed by option_input_key. additional_info: type: string description: Optional free-text additional information. skip: type: boolean description: Send true, without values, to skip an optional question explicitly. values_key: type: string description: Select one grid item; value[values_key] is then required. option_input_key: type: string description: >- Select one follow-up item; option_inputs[option_input_key] is then required. required: - question_key GuidedQuestion: type: object properties: question_key: type: string description: >- Stable key of the parent question. Use it in answer, back and submit payloads. type: type: string description: >- Input type, including likert-grid-item, option-input and conditional-field for sub-items. kind: type: string description: Answer kind used to choose a value shape. title: type: string description: Localized title of this item. question_title: type: string description: Localized title of the parent question. help: type: string description: Localized help text; empty when there is none. options: type: array items: $ref: '#/components/schemas/GuidedOption' description: Allowed values with localized labels. constraints: allOf: - $ref: '#/components/schemas/GuidedConstraints' description: Validation limits for this item. fields: type: array items: type: object additionalProperties: {} description: Named input fields for input and grid questions. sections: type: array items: type: object additionalProperties: {} description: Section layout for grid questions. conditional_fields: type: object additionalProperties: {} description: Named conditional fields and the options that require details. values_key: type: string description: 'Present on a grid item: send the value under value[values_key].' option_input_key: type: string description: >- Present on a follow-up item: send the value under option_inputs[option_input_key]. parent_question_title: type: string description: Localized title of the parent question of a sub-item. validation: type: object additionalProperties: {} description: Additional client-side validation hints. saved_answer: type: object additionalProperties: {} nullable: true description: The answer currently saved in the draft, or null. whyWeAsk: type: string description: Localized explanation of why the question is asked. helpDescription: type: string description: Longer localized help text. placeholder: type: string description: Localized input placeholder. cautionMessage: type: string description: Localized caution shown with the question. hint: type: string description: Localized short hint. learnMore: type: string description: Localized learn-more text. required: - conditional_fields - constraints - fields - help - kind - options - question_key - question_title - sections - title - type GuidedProgress: type: object properties: answered: type: integer description: Applicable items answered or explicitly skipped. total_applicable: type: integer description: >- Applicable items, including grid items and active required follow-ups. percent: type: number format: double description: >- answered as a percentage of total_applicable. Optional questions can keep it below 100 when submission is ready. required: - answered - percent - total_applicable GuidedDroppedInputs: type: object properties: question_key: type: string description: Parent question whose follow-up values were removed. option_input_keys: type: array items: type: string description: The removed follow-up keys. required: - option_input_keys - question_key GuidedOption: type: object properties: value: oneOf: - type: string - type: number - type: boolean - type: array items: {} - type: object additionalProperties: {} description: Value to send in the answer. label: type: string description: Localized label. required: - label - value GuidedConstraints: type: object properties: required: type: boolean description: Whether an answer is required. min: type: number format: double description: Minimum numeric value. max: type: number format: double description: Maximum numeric value. units: type: string description: Unit of a numeric value. min_selections: type: integer description: Minimum selections for multi-select. max_selections: type: integer description: Maximum selections for multi-select. accepted_upload_purpose: type: string nullable: true description: Document purpose an upload must have, or null. max_bytes: type: integer description: Maximum upload size in bytes. accept: type: array items: type: string description: Accepted upload media types. maxSizeMB: type: number format: double description: Maximum upload size in megabytes. multiple: type: boolean description: Whether several uploads are allowed. required: - required securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.