Pagination in the Hi Doctor patient REST API

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?

{
  "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

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 shows the origin check.

Examples

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

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

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"])

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.

Start

Conventions

Endpoints

Pagination in the Hi Doctor patient REST API

What does a paginated response look like?

Which shape does each list endpoint return?

How do you page through a list safely?

Examples

Next steps

Quickstart

Errors and recovery

Messages

​What does a paginated response look like?

​Which shape does each list endpoint return?

​How do you page through a list safely?

​Examples

​Next steps

Quickstart

Errors and recovery

Messages

What does a paginated response look like?

Which shape does each list endpoint return?

How do you page through a list safely?

Examples

Next steps