Skip to main content
The Hi Doctor REST API lets your own application do, on a patient’s behalf, what that patient can do on hi-doctor.ai: answer a questionnaire, pay for a consultation, read consultations and prescriptions, message the medical team and upload health documents. Every call acts for one signed-in patient account and starts at https://api.hi-doctor.ai/v1/. Start with the quickstart, or use the MCP connector if an AI assistant acts for the patient. Last reviewed: 2026-11-04 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.
Base URL
All paths start with /v1/. The root URL returns 404 by design; to check that the API is reachable, call GET /v1/system/healthcheck/.

​
Who can use the API?

The API acts for one patient at a time, with that patient’s own sign-in. There is no separate developer key: your application obtains the patient’s access token as described in Authentication and sends it on each request. A company building Hi Doctor into its product should first read Integrate Hi Doctor and Data and consent. Only patient endpoints are documented. Other endpoints are not part of the supported surface, and a patient token cannot use them. Every endpoint is scoped to the signed-in account: there is no patient identifier to pass, and a record that belongs to another account returns 404.

​
Which endpoints need a token?

Most endpoints need Authorization: Bearer <access token>. These do not: Questionnaire categories and schemas are public, so you can build your interface before a patient signs in. Saving and submitting answers needs a token.

​
Which header does every request need?

Send X-Brand-Slug: hi-doctor on every request, including sign-in, registration, verification, password reset and Google sign-in.
  • An unknown value is refused with 400 and {"code": "unknown_brand"}.
  • A missing or empty header currently falls back to hi-doctor, but do not rely on that: send the header explicitly.
The header is not a credential. It grants no access on its own.

​
Which content types does the API use?

  • JSON is the default for requests and responses.
  • Multipart form data is used for three uploads: consultation photos, health documents and message attachments. Sending JSON to a multipart endpoint returns 415.
  • Binary downloads (prescription PDFs, invoices, credit notes, documents, photos and attachments) stream bytes. Send Accept: */*; a strict Accept: application/pdf is refused with 406.
See Uploads and downloads for field names, limits and how to save a download to a file.

​
How are lists paginated?

There is no single list envelope. Most collections use limit/offset pagination and return {count, next, previous, results}, including conversation messages. Orders, health documents and consultation photos return a bare JSON array, and pending renewal choices return {"pending": [...]}. Pagination has the per-endpoint table, defaults, maximums and a safe way to follow next.

​
How are errors and throttling reported?

The API does not use one error envelope. Depending on the endpoint you get a field map, a detail string, or an error with code or error_name. Errors documents each shape and what your client should do with each status. Throttling happens in the application, not only in front of it:
  • Sign-in is throttled per IP address and per email, and account deletion is throttled per account.
  • Registration, forgot-password and the verification code have cooldowns. These also return 429 with Retry-After, and repeat the same number of seconds in the body as wait_seconds and retry_after_seconds.
Every 429 from these endpoints carries a Retry-After header in whole seconds. A 429 can come from any endpoint, including from infrastructure in front of the API. Handle it everywhere, back off, and never retry in a tight loop. For writes that can time out, use Idempotency-Key.

​
What is the typical patient flow?

1

Sign in

POST /v1/users/token/ returns an access and a refresh token. New patients start with Sign up.
2

Complete the profile

PATCH /v1/users/profile/me/. Checkout refuses with PROFILE_INCOMPLETE and a missing_fields list if anything required is absent.
3

Answer a questionnaire

GET /v1/users/questionnaires/categories/, pick a slug, then either run the guided questionnaire one question at a time, or save answers with PATCH .../progress/. Finish with POST .../submit/.
PATCH .../progress/ replaces the whole answer array. Always send the full cumulative set; anything you omit is erased.
4

Pay

POST /v1/users/checkout/ returns a Stripe checkout URL, or reports that an active plan already covers the consultation. Read GET /v1/users/stripe/session/{session_id}/ for the outcome.
5

Follow up

Read consultations and prescriptions, message the medical team, and record progress. The Account and Consultations group pages describe each endpoint group.

​
Should you use the REST API or the MCP connector?

Use the REST API

For your own application’s server: a patient app, a back end that syncs records, or an integration that is not driven by a model. Your server holds the tokens.

Use the MCP connector

For an AI assistant acting for a patient. Sign-in happens on hi-doctor.ai through OAuth, permissions are granted per scope, and the assistant never sees a password or a backend token.
Never put a patient’s password or a backend token into a model prompt. If a model is involved, use the MCP connector.

​
What can the API not do?

Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. Approving a consultation, issuing a prescription and changing a dose are therefore not in this API, and no patient token can perform them. Clinical eligibility is checked when the questionnaire is submitted; an ineligible result is a clinical outcome, not an error to work around. See Safety.

​
Frequently asked questions

​
Do I need an API key to use the Hi Doctor API?

No. The API acts for one patient at a time with that patient’s own access token. There is no separate developer key.

​
Can one access token read another patient’s records?

No. Every endpoint is scoped to the signed-in account, and a record that belongs to another account returns a not-found error.

​
Can the API approve a consultation or issue a prescription?

No. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. Clinical decisions are not part of the API.

​
Which countries can patients live in?

Residents of all 27 EU member states can use Hi Doctor. The full list with country codes is on Countries.

​
Should an AI assistant call the REST API directly?

No. An assistant acting for a patient should use the MCP connector, where sign-in happens on hi-doctor.ai and the assistant never sees a password or a token.

​
Is there an OpenAPI specification?

Yes. The public OpenAPI file is published at docs.hi-doctor.ai/api-reference/openapi.json, and every endpoint has its own reference page with code samples.

​
Where do I start?

Follow the REST API quickstart to sign in and make your first reads, then Answer a questionnaire.

​
Next steps

Quickstart

Sign a patient in and make your first authenticated reads in curl, Python and JavaScript.

Authentication

Access and refresh tokens, expiry, Google sign-in and sign-in failures.

Sign up

Register a patient, verify the emailed code and complete the profile.

Errors and recovery

Error shapes, throttles and how to recover from an uncertain write.