> ## 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.

# API reference

> The patient-facing Hi-Doctor REST API: sign in, complete a consultation, manage a plan, and track progress from your own code.

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.

```text Base URL theme={null}
https://api.hi-doctor.ai
```

Start with [Authentication](/api-reference/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:

| Group                            | Endpoints                                                                                                 | Header                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Getting a token**              | `register`, `verify-email`, `token`, `token/refresh`, `google-login`, `forgot-password`, `reset-password` | `X-Brand-Slug: hi-doctor` **required** |
| **Public questionnaire content** | `questionnaires/categories/`, `questionnaires/{slug}/schema/`                                             | none                                   |
| Everything else                  | —                                                                                                         | bearer token                           |

<Note>
  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.
</Note>

## 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.

<Warning>
  **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.
</Warning>

## Typical flow

<Steps>
  <Step title="Sign in">
    `POST /v1/users/token/` → access + refresh tokens.
  </Step>

  <Step title="Complete your profile">
    `PATCH /v1/users/profile/me/`. Checkout refuses with `PROFILE_INCOMPLETE`
    and a `missing_fields` list if anything required is absent.
  </Step>

  <Step title="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/`.

    <Warning>
      `PATCH .../progress/` **replaces the whole answer array** — it is not a
      merge. Always send the full cumulative set; anything you omit is erased.
    </Warning>

    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](/mcp/ai-integration) instead — it
    asks one question at a time and the server owns the branching.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Follow up">
    Read `/v1/users/consultations/` and `/v1/users/prescriptions/`, message via
    `/v1/users/conversations/`, and track progress under `/v1/users/journal/`.
  </Step>
</Steps>

## 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](/api-reference/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.

<Warning>
  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.
</Warning>

## Building an AI assistant?

Prefer the [MCP connector](/mcp/overview) 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.