Skip to main content
Three Hi Doctor REST endpoints accept file uploads as multipart/form-data: consultation photos, health documents and message attachments. Several others return file bytes, such as prescription PDFs, invoices and stored documents, streamed directly from the API with no signed redirect URLs. Uploads accept an Idempotency-Key, and downloads need Accept: */*. Last reviewed: 2026-11-04
These files are health data. Never write document bytes, photos or their contents to logs, analytics, error trackers or model prompts. Save them to a file with restricted access, or pass them straight to the patient.

How do you upload a file?

For health documents, kind is prescription, lab_result, photo or other (the default), and note is up to 500 characters. consultation_id must be one of your own consultations.
Do not set Content-Type by hand for multipart requests; your HTTP client adds the boundary. Sending JSON to an upload endpoint returns 415 Unsupported media type "application/json" in request.

Retry an upload safely

Photo uploads, document uploads and messages (including attachments) accept an Idempotency-Key header. Send the same key on every attempt and the upload is stored at most once. Without a key, a retry after a timeout can store a duplicate, so list the documents or photos first. A health document can be removed with DELETE /v1/users/documents/{document_id}/ and a consultation photo with DELETE /v1/questionnaire/consultations/{id}/images/{image_id}/. Both return 204 and also accept an Idempotency-Key.

How do you download a file?

  • Prescription kind is rempe (the electronic prescription kind) or english (the prescription document kind, an English PDF). Any other value returns 404.
  • Invoices and credit notes accept an optional ?locale= query parameter.
  • Photo, document, attachment, invoice and credit-note responses are sent with Cache-Control: private, no-store. Do not keep them in shared caches.

Always send Accept: */*

The PDF routes refuse a strict Accept: application/pdf with 406 Could not satisfy the request Accept header. Many HTTP clients set a specific Accept by default, so set */* explicitly.

Save to a file

Never parse a download as JSON. Check the status first: error responses are JSON, successful ones are bytes.

Errors

See Errors for envelopes and retry advice.

Can the MCP connector upload files?

Yes, with an MCP client that supports it. The MCP connector uploads consultation photos, health documents and message attachments through a protected upload: the client uploads the file first and the tool receives a file_ref, never the raw bytes in a prompt. Use this REST API when your own application handles the files.

Frequently asked questions

Which file types can a patient upload?

Consultation photos can be JPEG, PNG or WebP. Health documents can be PDF, PNG, JPEG or WebP, detected from the file bytes.

How large can an upload be?

A consultation photo can be up to 10 MiB, and a health document up to 20 MiB. A consultation holds at most 10 photos and a patient at most 50 documents.

Are uploads idempotent?

Yes, when you send an Idempotency-Key header. With the same key on every attempt, the upload is stored at most once; without a key, list the files before retrying.

Why does a PDF download return 406?

The PDF routes refuse a strict Accept header for PDF only. Send an Accept header with the any-type wildcard, as in the examples above, and the download works.

What is the difference between the two prescription PDF kinds?

One kind is the electronic prescription and the other is the prescription document, an English PDF. Any other kind value returns a not-found error.

Why does a download return 410?

The stored file can no longer be recovered. Do not retry; contact support if the patient needs the file.

Should I set the multipart Content-Type header myself?

No. Let your HTTP client set it, so the multipart boundary is included. Sending JSON to an upload endpoint returns 415.

Next steps

Safe retries

Upload or delete a file at most once with Idempotency-Key.

Consultations

Consultation photo endpoints and limits.

Records

Health document endpoints.

Prescriptions

List prescriptions and download their PDFs.