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

> ## Agent Instructions
> Connect the Hi Doctor MCP connector at https://mcp.hi-doctor.ai/mcp. Add this URL as a remote HTTP MCP server in your client, then sign in and authorise access through OAuth. Setup: https://docs.hi-doctor.ai/mcp/connect.
>
> The REST API base is https://api.hi-doctor.ai. Hi Doctor Docs at https://docs.hi-doctor.ai/mcp searches documentation; connect to the product endpoint above for patient tools.
>
> 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. Every consultation is reviewed in full by an EU-licensed doctor, who decides on medical grounds only. No algorithm, assistant or API call approves a consultation, issues a prescription or changes a dose. The service is available in eight languages: English, Spanish, German, Dutch, Italian, French, Portuguese and Chinese.
>
> ## Rules an assistant must follow
>
> - Never invent, assume or infer a medical answer. "I don't know" is a real answer: ask the patient to pick the closest option rather than guessing for them.
> - Never give medical advice and never suggest a medication or a dose. An EU-licensed doctor decides those.
> - If a questionnaire returns `ineligible`, say so plainly. Do not retry with altered answers.
> - Before anything that costs money or cancels a plan, state exactly what will happen and get an explicit yes.
> - Cancellation takes effect at the **end of the paid period**, not immediately. Say so.
> - An early order is irreversible: it creates the renewal consultation immediately and uses up the period's one early order. Explain that and get an explicit yes.
> - Prescription and invoice links are medical documents. A `signed_redirect` link opens without signing in: give it only to the patient, never repeat it anywhere shared.
> - Send option `value`s, not the labels shown to the patient. Labels are translated, values are stable.
> - Never ask for card details. Payment happens on Stripe's hosted checkout via a link.
> - On severe or sudden symptoms (chest pain, difficulty breathing, severe allergic reaction, suicidal thoughts), stop and direct the patient to their local emergency number.

# Pagination in the Hi Doctor patient REST API

> Which Hi Doctor list endpoints are paginated, which return bare arrays, the limit and offset defaults, and how to follow next safely.

The Hi Doctor patient REST API has no single list envelope. Most collections are paginated with `limit` and `offset` and return `count`, `next`, `previous` and `results`, with 50 rows by default and up to 200 on the default paginator. A few return a bare JSON array, and pending renewal choices return an object with a `pending` array, so check the shape per endpoint before reading `results`.

Last reviewed: 2026-11-04

## What does a paginated response look like?

```json theme={null}
{
  "count": 42,
  "next": "https://api.hi-doctor.ai/v1/users/consultations/?limit=10&offset=10",
  "previous": null,
  "results": [ ... ]
}
```

`next` and `previous` are absolute URLs, or `null` at either end.

| Parameter | Default | Maximum |
| - | - | - |
| `limit` | 50 | 200 on the default paginator (see the table below for exceptions) |
| `offset` | 0 | |

## Which shape does each list endpoint return?

| Endpoint | Shape | Notes |
| - | - | - |
| `GET /v1/users/questionnaires/categories/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/consultations/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/prescriptions/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/conversations/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/conversations/{id}/messages/` | Envelope | Maximum 200. `ordering` is `-created_at` (default, newest first) or `created_at` |
| `GET /v1/users/payments/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/referrals/me/referred/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/referrals/me/transactions/` | Envelope | Default paginator, maximum 200 |
| `GET /v1/users/adverse-events/` | Envelope | Default 50, no documented maximum |
| `GET /v1/users/journal/weight-entries/` | Envelope | Default 50, no documented maximum |
| `GET /v1/users/journal/injections/` | Envelope | Default 50, no documented maximum |
| `GET /v1/users/journal/notes/` | Envelope | Default 50, no documented maximum |
| `GET /v1/users/orders/` | Bare array | No envelope |
| `GET /v1/users/documents/` | Bare array | No envelope |
| `GET /v1/questionnaire/consultations/{id}/images/` | Bare array | No envelope |
| `GET /v1/users/subscriptions/pending-choice/` | `{"pending": [...]}` | Not paginated |

> [!NOTE]
>
> For the journal and adverse-event lists, no maximum `limit` is documented.
> Request a sensible page size (for example 50) and follow `next`, rather than
> asking for everything in one call.

## How do you page through a list safely?

* **Follow `next`.** Do not compute offsets yourself, and keep the same
  `limit` and `ordering` for the whole walk.
* **Pages can shift.** Offsets are positions, not cursors. If records are
  added or removed while you are paging (a new message arrives, for example),
  an item can appear twice or be skipped. Deduplicate by `id`, and re-read
  from the first page when you need a complete, current view.
* **Messages**: with the default `-created_at` ordering, new messages land on
  the first page. Equal timestamps have no further tie-breaker.
* **Stop on `null`.** When `next` is `null`, you have the last page.
* **Check `next` before sending a token to it.** Require the same HTTPS
  origin as your configured API origin and the same collection path, reject
  URLs with credentials or fragments, and disable redirects. The
  [quickstart](https://docs.hi-doctor.ai/api-reference/quickstart.md) shows the origin check.

## Examples

The examples keep the walk short for readability. In production, add the
`next` check above and a page cap.

```bash curl theme={null}
url="$HD_BASE_URL/v1/users/conversations/$CONVERSATION_ID/messages/?limit=50"
while [ -n "$url" ] && [ "$url" != "null" ]; do
  page=$(curl -s "$url" \
    -H "Authorization: Bearer $HD_ACCESS_TOKEN" \
    -H "X-Brand-Slug: hi-doctor")
  echo "$page" | python3 -c 'import json,sys; [print(m["id"]) for m in json.load(sys.stdin)["results"]]'
  url=$(echo "$page" | python3 -c 'import json,sys; print(json.load(sys.stdin)["next"] or "")')
done
```

```python Python theme={null}
import os
import requests

base = os.environ.get("HD_BASE_URL", "https://api.hi-doctor.ai")
headers = {
    "Authorization": f"Bearer {os.environ['HD_ACCESS_TOKEN']}",
    "X-Brand-Slug": "hi-doctor",
}

def iterate(path, limit=50):
    url = f"{base}{path}?limit={limit}"
    seen = set()
    while url:
        r = requests.get(url, headers=headers, timeout=10)
        r.raise_for_status()
        body = r.json()
        for item in body["results"]:
            if item["id"] not in seen:
                seen.add(item["id"])
                yield item
        url = body["next"]

for payment in iterate("/v1/users/payments/"):
    print(payment["id"])
```

```javascript JavaScript theme={null}
const base = process.env.HD_BASE_URL ?? "https://api.hi-doctor.ai";
const headers = {
  Authorization: `Bearer ${process.env.HD_ACCESS_TOKEN}`,
  "X-Brand-Slug": "hi-doctor",
};

async function* iterate(path, limit = 50) {
  let url = `${base}${path}?limit=${limit}`;
  const seen = new Set();
  while (url) {
    const r = await fetch(url, { headers });
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    const body = await r.json();
    for (const item of body.results) {
      if (!seen.has(item.id)) {
        seen.add(item.id);
        yield item;
      }
    }
    url = body.next;
  }
}

for await (const p of iterate("/v1/users/payments/")) console.log(p.id);
```

For bare-array endpoints, read the response as a list directly; there is no
`next` to follow.

## Next steps

> [card] [Quickstart](https://docs.hi-doctor.ai/api-reference/quickstart.md)
>
> Sign in and make your first read.

> [card] [Errors and recovery](https://docs.hi-doctor.ai/api-reference/errors.md)
>
> Handle 429 and other errors while paging.

> [card] [Messages](https://docs.hi-doctor.ai/api-reference/tags/messages.md)
>
> The message list and its ordering.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.