> ## 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. # Upload a photo or document > Uploads one file as multipart/form-data and returns an upload_id. Use the id as the answer to an upload question or in an information request answer. Pending uploads expire after 24 hours. Pending uploads count towards your storage quota (refused with 422 storage_quota_exceeded when full); an expired upload stops counting at expires_at, can no longer be used (422 upload_unusable) and is deleted, file included, by a periodic cleanup. Attached uploads are kept with the consultation. Requires the consultations:write scope. ### Access, effects and retries **Ownership:** The API key's own partner and mode (test or live). **Prerequisites:** A partner API key with the `consultations:write` scope. **Effects:** Stores one pending upload that counts towards the storage quota until it is attached or expires. **Retries:** Not replayed by Idempotency-Key: a retry stores a second upload. Unused uploads expire and are cleaned up. ## OpenAPI ````yaml /api-reference/partner/openapi.json post /v1/partner/files/ openapi: 3.0.3 info: title: Hi Doctor Partner API version: '1.0' description: >- The Hi Doctor Partner API lets a partner submit online medical consultations for its patients, follow their clinical review, answer the doctor's information requests and read the resulting prescriptions. Partner requests use Authorization: Bearer with a partner API key; test keys and live keys are separate. See https://docs.hi-doctor.ai/partners/overview for the partner 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: Connectivity description: Check that a key works. - name: Products description: What you can offer, where, and at what price. - name: Questionnaires description: The questions a patient answers for a product. - name: Files description: Photos and documents attached to answers. - name: Consultations description: Submit consultations and follow their review. - name: Patients description: The patients you submitted consultations for, and their consent. - name: Information requests description: Questions the doctor sends back during review. - name: Prescriptions description: Prescriptions issued after an approval. - name: Webhooks description: Receive events instead of polling. - name: Test mode description: Tools that only work with test keys. paths: /v1/partner/files/: post: tags: - Files summary: Upload a photo or document description: >- Uploads one file as multipart/form-data and returns an upload_id. Use the id as the answer to an upload question or in an information request answer. Pending uploads expire after 24 hours. Pending uploads count towards your storage quota (refused with 422 storage_quota_exceeded when full); an expired upload stops counting at expires_at, can no longer be used (422 upload_unusable) and is deleted, file included, by a periodic cleanup. Attached uploads are kept with the consultation. Requires the consultations:write scope. ### Access, effects and retries **Ownership:** The API key's own partner and mode (test or live). **Prerequisites:** A partner API key with the `consultations:write` scope. **Effects:** Stores one pending upload that counts towards the storage quota until it is attached or expires. **Retries:** Not replayed by Idempotency-Key: a retry stores a second upload. Unused uploads expire and are cleaned up. operationId: upload_file parameters: - in: header name: Idempotency-Key schema: type: string pattern: ^[A-Za-z0-9_-]{8,128}$ description: >- Accepted but not used for replay on this operation. Only POST /v1/partner/consultations stores and replays responses by Idempotency-Key. example: b7c1d2e3f4a5b6c7 requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FileUploadRequest' examples: example-1: summary: Illustrative request example value: file: purpose: photo required: true responses: '201': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/Upload' examples: example-1: value: upload_id: 3d4e5f60-7182-4934-a5b6-c7d8e9f0a1b2 object: upload purpose: photo content_type: image/jpeg bytes: 482113 sha256: width: 1600 height: 1200 status: pending expires_at: '2026-11-04T10:15:00Z' summary: Illustrative response example description: The stored upload. '400': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: invalid_request code: parse_error message: >- Multipart form parse error - Invalid boundary in multipart: None request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: invalid_request code: brand_header_not_allowed message: >- Brand headers are not accepted on partner requests; the brand comes from the API key. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: >- The request is malformed. Partner routes also refuse the patient-app brand header with 400 brand_header_not_allowed, before authentication (no rate-limit headers). '401': headers: WWW-Authenticate: schema: type: string description: >- The authentication scheme to use: Bearer realm="hi-doctor-partner". content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: authentication_error code: not_authenticated message: Authentication credentials were not provided. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: authentication_error code: invalid_token message: The API key is not valid. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-3: value: error: type: authentication_error code: key_revoked message: The API key has been revoked. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-4: value: error: type: authentication_error code: key_expired message: The API key has expired. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-5: value: error: type: authentication_error code: partner_suspended message: The partner account is suspended. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: >- The API key is missing, malformed, unknown, revoked or expired, or the partner account is suspended. The response carries WWW-Authenticate: Bearer realm="hi-doctor-partner" and no rate-limit headers. '403': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: permission_error code: insufficient_scope message: This endpoint requires the consultations:write scope. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: permission_error code: partner_not_live message: Live mode is not enabled for this partner. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: >- The key lacks the consultations:write scope (insufficient_scope), or a live key was used while live mode is not enabled for the partner (partner_not_live). '404': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: anyOf: - $ref: '#/components/schemas/PartnerError' - $ref: '#/components/schemas/PartnerFlagOffError' examples: example-1: value: error: type: not_found summary: Illustrative response example description: >- While the Partner API is switched off for the environment, every route answers 404 with only {"error": {"type": "not_found"}}, before authentication. '422': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: validation_error code: invalid_request message: >- Send a multipart 'file' and a purpose of photo or document. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-2: value: error: type: validation_error code: unsupported_media message: Only JPEG, PNG and PDF files are accepted. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-3: value: error: type: validation_error code: file_too_large message: The file exceeds 10 MB. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-4: value: error: type: validation_error code: image_too_large message: The image dimensions exceed the allowed limits. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-5: value: error: type: validation_error code: checksum_mismatch message: The sha256 does not match the uploaded bytes. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example example-6: value: error: type: validation_error code: storage_quota_exceeded message: The partner's pending upload storage is full. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: The request body is invalid. '429': headers: X-RateLimit-Limit: schema: type: integer description: >- Requests allowed in the current window for the most restrictive limit that applies. Absent on refusals made before the throttles run (brand header, flag off, partner_not_live). X-RateLimit-Remaining: schema: type: integer description: Requests left in the current window. X-RateLimit-Reset: schema: type: integer description: Unix time, in seconds, when the window frees up. Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/PartnerError' examples: example-1: value: error: type: rate_limited code: throttled message: Request was throttled. Expected available in 12 seconds. request_id: req_5f0c3a9d2b7e4f18a6c1d9e3b2a7f4c8 summary: Illustrative response example description: Too many requests; wait for the number of seconds in Retry-After. security: - PartnerApiKey: [] 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/partner/files/${HD_QUERY_STRING:+?${HD_QUERY_STRING}}" printf 'Accept: application/json\n' > "${HD_REQUEST_HEADERS_FILE:?Private header file}" printf 'Authorization: Bearer %s\n' "${HD_PARTNER_API_KEY:?Set partner API key}" >> "$HD_REQUEST_HEADERS_FILE" form_args=() while IFS= read -r -d "" form_value; do form_args+=(--form-string "$form_value") done < <(python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); [sys.stdout.write(str(k)+"="+str(v)+"\0") for k,v in d.items() if v is not None]' "${HD_REQUEST_FILE:?JSON form fields}") 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' \ --form 'file=@'"${HD_UPLOAD_FILE:?Synthetic upload};type=${HD_UPLOAD_CONTENT_TYPE:?Upload MIME}" \ ${form_args[@]+"${form_args[@]}"} \ "$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/partner/files/' if os.environ.get("HD_QUERY_STRING"): url += "?" + os.environ["HD_QUERY_STRING"] headers = {"Accept": 'application/json'} headers["Authorization"] = "Bearer " + os.environ["HD_PARTNER_API_KEY"] kwargs = {} kwargs["files"] = {'file': ("synthetic-upload", Path(os.environ["HD_UPLOAD_FILE"]).read_bytes(), os.environ["HD_UPLOAD_CONTENT_TYPE"])} kwargs["data"] = 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/partner/files/"; if (env.HD_QUERY_STRING) url += "?" + env.HD_QUERY_STRING; const headers = { "Accept": "application/json" }; headers.Authorization = "Bearer " + env.HD_PARTNER_API_KEY; const options = { method: "POST", headers, redirect: "manual", signal: AbortSignal.timeout(30000) }; options.body = new FormData(); options.body.append("file", new Blob([readFileSync(env.HD_UPLOAD_FILE)], {type: env.HD_UPLOAD_CONTENT_TYPE}), "synthetic-upload"); for (const [key, value] of Object.entries(JSON.parse(readFileSync(env.HD_REQUEST_FILE, "utf8")))) { if (value != null) options.body.append(key, String(value)); } 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: FileUploadRequest: type: object properties: file: type: string format: binary description: >- JPEG, PNG or PDF, at most 10 MB. The type is detected from the bytes. purpose: allOf: - $ref: '#/components/schemas/UploadPurposeEnum' default: photo description: photo or document. sha256: type: string description: Optional hex digest; a mismatch is refused. required: - file Upload: type: object properties: upload_id: type: string format: uuid description: The upload id; use it as the answer to an upload question. object: allOf: - $ref: '#/components/schemas/UploadObjectEnum' description: Always upload. purpose: allOf: - $ref: '#/components/schemas/UploadPurposeEnum' description: photo or document. content_type: type: string description: Detected content type of the file. bytes: type: integer description: File size in bytes. sha256: type: string description: SHA-256 hex digest of the file. width: type: integer nullable: true description: Image width in pixels; null for documents. height: type: integer nullable: true description: Image height in pixels; null for documents. status: allOf: - $ref: '#/components/schemas/UploadStatusEnum' description: >- pending until a consultation or information request answer uses it (attached). An upload never used before expires_at is expired: it no longer counts towards the storage quota, cannot be used, and is deleted with its file by a periodic cleanup. expires_at: type: string format: date-time nullable: true description: When the upload expires if it is still unused. required: - bytes - content_type - expires_at - height - object - purpose - sha256 - status - upload_id - width PartnerError: type: object properties: error: allOf: - $ref: '#/components/schemas/PartnerErrorDetail' description: The error. required: - error PartnerFlagOffError: type: object description: >- The reduced body every route answers while the Partner API is switched off for the environment: no code, message or request_id. properties: error: type: object properties: type: type: string enum: - not_found description: Always not_found. required: - type additionalProperties: false description: Only the error type; no code, message or request_id. required: - error additionalProperties: false UploadPurposeEnum: enum: - photo - document type: string UploadObjectEnum: enum: - upload type: string UploadStatusEnum: enum: - pending - attached - expired type: string PartnerErrorDetail: type: object properties: type: allOf: - $ref: '#/components/schemas/PartnerErrorDetailTypeEnum' description: >- Error type, for example validation_error or rate_limited; see Errors in the partner guides. code: type: string description: A stable, machine-readable error code. message: type: string description: A human-readable explanation; do not parse it. errors: type: array items: $ref: '#/components/schemas/PartnerErrorItem' description: Field-level problems, when any. request_id: type: string description: Quote this identifier when you contact support. current: allOf: - $ref: '#/components/schemas/SchemaVersion' description: >- On 409 schema_outdated: the schema_version and schema_hash currently published. current_notice_version: type: string description: >- On 422 consent_notice_outdated: the patient notice version to show and record. required: - code - message - request_id - type PartnerErrorDetailTypeEnum: enum: - api_error - authentication_error - conflict - invalid_request - not_found - permission_error - rate_limited - validation_error type: string PartnerErrorItem: type: object properties: field: type: string nullable: true description: The request field the problem refers to, or null when none. question_key: type: string nullable: true description: >- The questionnaire question the problem refers to, or null when the entry named none. code: type: string description: Machine-readable error code for this item. message: type: string description: Human-readable message. It never repeats the submitted value. min: type: number format: double description: 'On out_of_range: the lowest allowed value, when the schema sets one.' max: type: number format: double description: >- On out_of_range: the highest allowed value, when the schema sets one. required: - code - message SchemaVersion: type: object properties: schema_version: type: string description: The published schema_version. schema_hash: type: string description: A hash accepted for the published version. required: - schema_hash - schema_version securitySchemes: PartnerApiKey: type: http scheme: bearer bearerFormat: API key description: >- Partner API key sent as Authorization: Bearer . Test keys and live keys are separate. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.