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
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 anIdempotency-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
kindisrempe(the electronic prescription kind) orenglish(the prescription document kind, an English PDF). Any other value returns404. - 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 afile_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.