> ## 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. # Create a medical-team conversation > Gets or creates the patient's own thread with the medical team. ### Access, effects and retries **Ownership:** Patient own conversation. **Prerequisites:** Authentication and permission to access the consultation are required. **Effects:** get_or_create conversation. **Retries:** Existing returns 200; new returns 201. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/users/conversations/ 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/conversations/: post: tags: - Messages summary: Create a medical-team conversation description: >- Gets or creates the patient's own thread with the medical team. ### Access, effects and retries **Ownership:** Patient own conversation. **Prerequisites:** Authentication and permission to access the consultation are required. **Effects:** get_or_create conversation. **Retries:** Existing returns 200; new returns 201. operationId: users_conversations_create parameters: - in: header name: Idempotency-Key required: false schema: type: string pattern: ^[A-Za-z0-9_-]{8,128}$ description: >- Optional key that makes a retry safe. Generate one value per logical operation (8 to 128 ASCII letters, digits, underscores or hyphens) and resend the same value on every retry. A repeat of a completed request returns its original status with `Idempotent-Replayed: true` and a short body of `state`, `resource_ids` and `response_hash`; read the resources to recover their content. Reusing a key with a different request returns 422 `idempotency_key_reuse`; a request still running returns 409 `idempotency_in_progress`. Keys are kept for 30 days. See https://docs.hi-doctor.ai/api-reference/idempotency. example: op-7f3a9c2e-0b1d-4e5f-9a8b-1c2d3e4f5a6b requestBody: required: true content: application/json: schema: type: object additionalProperties: {} examples: example-1: summary: Captured request example value: {} example-2: summary: Captured request example value: {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/Conversation' examples: example-1: summary: Illustrative response example value: id: b9b42152-b531-575c-b67c-c17cd8d6df5c user: id: 0a1b1763-0fca-5634-825c-381c65938c12 email: synthetic-patient@example.invalid first_name: Synthetic first name last_name: Synthetic last name locale: en created_at: '2026-10-05T17:48:42.193641Z' updated_at: '2026-10-05T17:48:42.193654Z' is_active: true pinned_at: null last_message: null last_message_created_at: null last_message_sender_type: null unread_count: 0 subscription_status: null example-2: summary: Captured response example value: id: 22d29e0a-2eb4-57e7-8957-081968bbb77a user: id: 9fb1a263-c71b-5fe9-b2e7-5a0eb099bad5 email: synthetic-patient@example.invalid first_name: Synthetic first name last_name: Synthetic last name locale: en created_at: '2026-10-05T18:21:46.983868Z' updated_at: '2026-10-05T19:51:12.696617Z' is_active: true pinned_at: null last_message: id: f6110c21-3333-5fbd-8fd3-e7f644f0a9d0 sender: 788df1b1-751a-57b4-be60-54c545313bdf sender_type: SYSTEM content: >- We have received your side effect report. Your doctor will review it and reply here in this chat. file: null file_name: null file_content_type: null file_available: true is_read: false created_at: '2026-10-05T19:51:12.695790Z' audience: patient event_type: adverse_event_received event_params: report_id: 0beb8635-b5df-5e33-abcc-a9e6870f8986 translation_enabled: true translation_default_on: true last_message_created_at: '2026-10-05T19:51:12.695790Z' last_message_sender_type: SYSTEM unread_count: 7 subscription_status: null description: Successful create a medical-team conversation. '201': content: application/json: schema: $ref: '#/components/schemas/Conversation' examples: example-1: summary: Illustrative response example value: id: b9b42152-b531-575c-b67c-c17cd8d6df5c user: id: 0a1b1763-0fca-5634-825c-381c65938c12 email: synthetic-patient@example.invalid first_name: Synthetic first name last_name: Synthetic last name locale: en created_at: '2026-10-05T17:48:42.193641Z' updated_at: '2026-10-05T17:48:42.193654Z' is_active: true pinned_at: null last_message: null last_message_created_at: null last_message_sender_type: null unread_count: 0 subscription_status: null description: Successful create a medical-team conversation. '400': description: Source-defined error response; inspect the envelope and retry rules. content: application/json: schema: type: object additionalProperties: {} description: >- Endpoint/DRF error envelope; field validation is keyed by request field. examples: example-1: summary: Illustrative response example value: detail: Invalid input. '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 account lacks permission for this operation. 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. '404': description: Request failed with the documented source error envelope. content: application/json: examples: example-1: summary: Illustrative response example value: error: User not found 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: {} '409': description: >- A request with this Idempotency-Key is still running, or the key has expired (`idempotency_key_expired`). Wait and retry with the same key, or reconcile with the idempotency lookup. content: application/json: schema: type: object description: Idempotency error. `code` names the reason. properties: code: type: string description: Machine-readable reason. required: - code examples: example-1: summary: Illustrative response example value: code: idempotency_in_progress '422': description: >- The Idempotency-Key was already used with a different request. Generate a new key only for a genuinely new operation. content: application/json: schema: type: object description: Idempotency error. `code` names the reason. properties: code: type: string description: Machine-readable reason. required: - code examples: example-1: summary: Illustrative response example value: code: idempotency_key_reuse '429': description: Source-defined error response; inspect the envelope and retry rules. content: application/json: schema: type: object additionalProperties: {} description: >- Endpoint/DRF error envelope; field validation is keyed by request field. 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/conversations/${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/conversations/' 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/conversations/"; 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: Conversation: type: object properties: id: type: string format: uuid readOnly: true description: >- Unique identifier of this resource. Returned by the server; not writable. user: allOf: - $ref: '#/components/schemas/ConversationParticipant' readOnly: true description: User for this conversation. Returned by the server; not writable. created_at: type: string format: date-time readOnly: true description: >- Created at timestamp in ISO 8601 format. Returned by the server; not writable. updated_at: type: string format: date-time readOnly: true description: >- Updated at timestamp in ISO 8601 format. Returned by the server; not writable. is_active: type: boolean description: Whether active applies to this conversation. pinned_at: type: string format: date-time nullable: true description: >- Pinned at timestamp in ISO 8601 format. May be null when unavailable. last_message: readOnly: true description: The most recent message. **Null when the thread is empty.** anyOf: - $ref: '#/components/schemas/ConversationMessage' - enum: - null type: string nullable: true last_message_created_at: type: string format: date-time nullable: true readOnly: true description: >- Last message created at timestamp in ISO 8601 format. Returned by the server; not writable. May be null when unavailable. last_message_sender_type: type: string enum: - USER - ADMIN - DOCTOR - SYSTEM - null readOnly: true nullable: true description: >- Last message sender type for this conversation. Returned by the server; not writable. May be null when unavailable. unread_count: type: integer readOnly: true description: >- Unread count for this conversation. Returned by the server; not writable. subscription_status: type: string readOnly: true nullable: true description: >- Subscription status for this conversation. Returned by the server; not writable. May be null when unavailable. translation_target_lang: type: string nullable: true readOnly: true description: >- Translation target lang for this conversation. Returned by the server; not writable. May be null when unavailable. required: - created_at - id - last_message - last_message_created_at - last_message_sender_type - subscription_status - unread_count - updated_at - user ConversationParticipant: oneOf: - $ref: '#/components/schemas/ConversationUser' - $ref: '#/components/schemas/ConversationPatient' ConversationMessage: type: object description: A single message in the patient's thread with the medical team. properties: id: type: string format: uuid description: Unique identifier of this resource. sender: type: string format: uuid description: Account id of the sender. sender_type: type: string enum: - USER - ADMIN - DOCTOR - SYSTEM description: >- Sender class, including automatic system messages; visibility is filtered to the caller. content: type: string nullable: true description: Text content of the resource. May be null when unavailable. file: type: string format: uri nullable: true description: File for this conversation message. May be null when unavailable. is_read: type: boolean description: Whether read applies to this conversation message. created_at: type: string format: date-time description: Created at timestamp in ISO 8601 format. translation_enabled: type: boolean description: Whether translation enabled applies to this conversation message. translation_default_on: type: boolean description: Whether translation default on applies to this conversation message. source_text: type: string description: Original message text, emitted only to internal actors. nullable: true file_name: type: string description: Display name of the attached file, or null. nullable: true file_content_type: type: string description: Attachment media type, or null. nullable: true event_type: type: string description: Machine event identifier, or null for an ordinary message. nullable: true file_available: type: boolean description: Whether the authorized attachment remains available. audience: type: string description: >- Message audience. Patient requests return only patient-visible messages. enum: - patient - staff event_params: description: Structured JSON event parameters; null for an ordinary message. translation: type: object description: Cached translation, present only when available. properties: translated_text: type: string description: Translated message text. detected_source_lang: type: string description: Detected language code; null when unknown. nullable: true required: - translated_text - detected_source_lang ConversationUser: type: object description: |- Read-only nested user for conversation payloads. Carries country_of_residence for the doctor inbox (residence flag beside the patient name) without touching the registration UserSerializer, whose field set doubles as the write contract for sign-up. properties: id: type: string format: uuid readOnly: true description: >- Unique identifier of this resource. Returned by the server; not writable. email: type: string format: email readOnly: true description: Account email address. Returned by the server; not writable. first_name: type: string readOnly: true description: >- First name for this conversation user. Returned by the server; not writable. last_name: type: string readOnly: true description: >- Last name for this conversation user. Returned by the server; not writable. country_of_residence: type: string readOnly: true nullable: true description: >- ISO 3166-1 alpha-3 country code where the patient currently lives. Used for EU cross-border prescription dispensing guidance. required: - country_of_residence - email - first_name - id - last_name ConversationPatient: type: object properties: id: type: string format: uuid readOnly: true description: >- Unique identifier of this resource. Returned by the server; not writable. email: type: string format: email maxLength: 254 description: Account email address. Maximum 254 characters. first_name: type: string maxLength: 150 description: First name for this conversation patient. Maximum 150 characters. last_name: type: string maxLength: 150 description: Last name for this conversation patient. Maximum 150 characters. locale: allOf: - $ref: '#/components/schemas/LocaleEnum' description: Preferred email locale. required: - email - id LocaleEnum: enum: - de - en - es - fr - it - nl - pt type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.