Skip to main content
The Hi-Doctor API lets you do programmatically what a patient can do on hi-doctor.ai: complete a questionnaire, pay for a consultation, read prescriptions and payments, message the medical team, track progress, and manage a treatment plan.
Base URL
Start with Authentication, then browse the endpoints in the sidebar.

​
Scope of this reference

Only patient-accessible endpoints are documented. Clinician, pharmacy and back-office endpoints exist but are intentionally omitted — they are not available to a patient account and are not part of the supported surface.

​
What needs a token

Most endpoints need Authorization: Bearer <access token>. Three groups do not:
Questionnaire categories and schemas are genuinely public — you can fetch the question set and build your interface before a patient has signed in. Only answers need a token.X-Brand-Slug: hi-doctor is required on every unauthenticated auth endpoint, not only sign-in. Omitting it fails the request with the same 401 as a wrong password.

​
Conventions

  • All requests and responses are JSON, except PDF downloads.
  • All paths are prefixed with /v1/.
  • Timestamps are ISO 8601. Dates are YYYY-MM-DD.
  • Money is in euro cents unless a field name says otherwise.
  • Most list endpoints are paginated as { "count": N, "next": url|null, "previous": url|null, "results": [...] } and accept limit and offset. Follow next rather than incrementing offset yourself; page_size is not a recognised parameter and is ignored.
Not every list endpoint is paginated. GET /v1/users/orders/ and GET /v1/users/conversations/{id}/messages/ return a bare JSON array with no envelope. Code that reaches straight for .results gets undefined on those two. Check the shape, or read the response example on each endpoint.

​
Typical flow

1

Sign in

POST /v1/users/token/ → access + refresh tokens.
2

Complete your 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 → GET /v1/users/questionnaires/{slug}/schema/ → save drafts with PATCH .../progress/ → finish with POST .../submit/.
PATCH .../progress/ replaces the whole answer array — it is not a merge. Always send the full cumulative set; anything you omit is erased.
Driving this by hand means evaluating the clinical branching yourself and tracking the cumulative answer set. If you are building a chat interface, use the conversational questionnaire instead — it asks one question at a time and the server owns the branching.
4

Pay

POST /v1/users/checkout/ returns either a Stripe checkout_url or covered_by_subscription when an active plan already covers it. Poll GET /v1/users/stripe/session/{session_id}/ for the outcome.
5

Follow up

Read /v1/users/consultations/ and /v1/users/prescriptions/, message via /v1/users/conversations/, and track progress under /v1/users/journal/.

​
Errors and rate limits

The API uses five different error envelopes depending on which layer refused the request — a client that reads only detail loses the message on most validation failures. Errors documents every shape, every status code, and whether to retry, re-authenticate or fix the input. Numeric rate limits are not published, and are enforced at the edge rather than by the endpoints themselves, so you cannot infer a budget by testing. Handle a 429 on any call: honour Retry-After if present, otherwise back off exponentially with jitter, and never retry in a tight loop.
On email verification, hammering the endpoint extends the lockout rather than shortening it, and a throttled registration retry deliberately does not invalidate the code already sitting in the patient’s inbox. Tell them to check for the earlier email rather than promising a new one.

​
Building an AI assistant?

Prefer the MCP connector over this API. It handles OAuth, per-permission scoping and the conversational questionnaire for you, and your application never handles the patient’s password. Use the REST API directly for server-side integrations that are not driven by a model.

​
Clinical boundaries

Approving a consultation, issuing a prescription and changing a dose are clinician actions. They are not in this API and cannot be performed by a patient token.