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

# List patient conversations

> Self-scoped.

### Access, effects and retries
**Ownership:** Patient own conversation.

**Prerequisites:** Authentication and permission to access the consultation are required.

**Effects:** Read only.

**Retries:** Read safe; ordering can shift as new messages arrive.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/users/conversations/
openapi: 3.0.3
info:
  title: Hi Doctor API
  version: 1.0.1
  description: >-
    The patient-facing Hi Doctor API supports account management, consultation
    questionnaires, medical documents, messages and billing. Sign-in requires
    X-Brand-Slug: hi-doctor; authenticated requests use Authorization: Bearer
    <access> with a JWT access token. See
    https://docs.hi-doctor.ai/api-reference/introduction for integration guides.
  contact:
    name: Hi Doctor
    email: hello@hi-doctor.ai
    url: https://docs.hi-doctor.ai
servers:
  - url: https://api.hi-doctor.ai
    description: Production
security: []
tags:
  - name: Account
    description: Register, verify, authenticate and manage the signed-in account.
  - name: Questionnaires
    description: Discover, save and submit consultation questionnaires.
  - name: Consultations
    description: Read consultation state and manage consultation photographs.
  - name: Prescriptions
    description: Retrieve issued prescription documents and request reissue.
  - name: Messages
    description: Read and send messages to the medical team, and download attachments.
  - name: Billing
    description: >-
      Create checkout, manage subscriptions and retrieve
      payments/invoices/credit notes.
  - name: Records
    description: Read orders and manage patient health documents.
  - name: Safety reports
    description: Submit and read suspected side-effect reports; no automated diagnosis.
  - name: Progress
    description: Record and review eligible weight-loss progress.
  - name: Referrals
    description: Read the signed-in account's referral summary and referral activity.
paths:
  /v1/users/conversations/:
    get:
      tags:
        - Messages
      summary: List patient conversations
      description: >-
        Self-scoped.


        ### Access, effects and retries

        **Ownership:** Patient own conversation.


        **Prerequisites:** Authentication and permission to access the
        consultation are required.


        **Effects:** Read only.


        **Retries:** Read safe; ordering can shift as new messages arrive.
      operationId: users_conversations_list
      parameters:
        - name: ordering
          required: false
          in: query
          description: Which field to use when ordering the results.
          schema:
            type: string
          example: synthetic
        - name: limit
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
          example: 1
        - name: offset
          required: false
          in: query
          description: The initial index from which to return the results.
          schema:
            type: integer
          example: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedConversationList'
              examples:
                example-1:
                  summary: Illustrative response example
                  value:
                    count: 0
                    next: null
                    previous: null
                    results: []
                example-2:
                  summary: Illustrative response example
                  value:
                    count: 0
                    next: null
                    previous: null
                    results: []
                example-3:
                  summary: Captured response example
                  value:
                    count: 1
                    next: null
                    previous: >-
                      https://api.hi-doctor.ai/v1/users/conversations/?limit=1&offset=999999
                    results: []
                example-4:
                  summary: Captured response example
                  value:
                    count: 1
                    next: null
                    previous: null
                    results:
                      - id: 22d29e0a-2eb4-57e7-8957-081968bbb77a
                        user:
                          id: 9fb1a263-c71b-5fe9-b2e7-5a0eb099bad5
                          email: synthetic-patient@example.invalid
                          first_name: Synthetic first name
                          last_name: Synthetic last name
                          locale: en
                        created_at: '2026-10-05T18:21:46.983868Z'
                        updated_at: '2026-10-05T19:38:30.179478Z'
                        is_active: true
                        pinned_at: null
                        last_message:
                          id: 0ca1c7d8-9dc8-5d0c-ab8a-6f01019836be
                          sender: 788df1b1-751a-57b4-be60-54c545313bdf
                          sender_type: SYSTEM
                          content: >-
                            Thank you for your order. Our staff will review it
                            shortly.
                          file: null
                          file_name: null
                          file_content_type: null
                          file_available: true
                          is_read: false
                          created_at: '2026-10-05T19:38:29.490648Z'
                          audience: patient
                          event_type: order_confirmation
                          event_params: {}
                        last_message_created_at: '2026-10-05T19:38:29.490648Z'
                        last_message_sender_type: SYSTEM
                        unread_count: 7
                        subscription_status: active
                example-5:
                  summary: Captured response example
                  value:
                    count: 1
                    next: null
                    previous: null
                    results:
                      - id: 22d29e0a-2eb4-57e7-8957-081968bbb77a
                        user:
                          id: 9fb1a263-c71b-5fe9-b2e7-5a0eb099bad5
                          email: synthetic-patient@example.invalid
                          first_name: Synthetic first name
                          last_name: Synthetic last name
                          locale: en
                        created_at: '2026-10-05T18:21:46.983868Z'
                        updated_at: '2026-10-05T19:51:12.696617Z'
                        is_active: true
                        pinned_at: null
                        last_message:
                          id: f6110c21-3333-5fbd-8fd3-e7f644f0a9d0
                          sender: 788df1b1-751a-57b4-be60-54c545313bdf
                          sender_type: SYSTEM
                          content: >-
                            We have received your side effect report. Your
                            doctor will review it and reply here in this chat.
                          file: null
                          file_name: null
                          file_content_type: null
                          file_available: true
                          is_read: false
                          created_at: '2026-10-05T19:51:12.695790Z'
                          audience: patient
                          event_type: adverse_event_received
                          event_params:
                            report_id: 0beb8635-b5df-5e33-abcc-a9e6870f8986
                        last_message_created_at: '2026-10-05T19:51:12.695790Z'
                        last_message_sender_type: SYSTEM
                        unread_count: 7
                        subscription_status: active
          description: Successful list conversations.
        '401':
          description: >-
            No bearer token, or a token that is expired or malformed.
            Re-authenticate; do not retry the same token.
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope emitted by the source branch or DRF validation.
                  `detail`, `error` and `code` depend on the branch; field
                  validation uses lists keyed by request field.
                additionalProperties: {}
              examples:
                example-1:
                  summary: Illustrative response example
                  value:
                    detail: Authentication credentials were not provided.
        '403':
          description: The account lacks permission for this operation.
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Error envelope emitted by the source branch or DRF validation.
                  `detail`, `error` and `code` depend on the branch; field
                  validation uses lists keyed by request field.
                additionalProperties: {}
              examples:
                example-1:
                  summary: Illustrative response example
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: Source-defined error response; inspect the envelope and retry rules.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
                description: >-
                  Endpoint/DRF error envelope; field validation is keyed by
                  request field.
              examples:
                example-1:
                  summary: Illustrative response example
                  value:
                    detail: Request was throttled.
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: >
            set -eu

            umask 077

            # Path values must be URL-encoded; query string excludes the leading
            question mark.

            url="${HD_BASE_URL:?Set API
            origin}/v1/users/conversations/${HD_QUERY_STRING:+?${HD_QUERY_STRING}}"

            printf 'X-Brand-Slug: hi-doctor\nAccept: application/json\n' >
            "${HD_REQUEST_HEADERS_FILE:?Private header file}"

            printf 'Authorization: Bearer %s\n' "${HD_ACCESS_TOKEN:?Set backend
            JWT}" >> "$HD_REQUEST_HEADERS_FILE"

            curl --silent --show-error --max-time 30 --request GET \
              --header "@$HD_REQUEST_HEADERS_FILE" \
              --dump-header "${HD_HEADERS_FILE:?Private response header file}" \
              --output "${HD_RESPONSE_FILE:?Private response file}" \
              --write-out '%{http_code}\n%{content_type}\n' \
              "$url"
        - lang: Python
          label: requests
          source: >
            import os, json

            from pathlib import Path

            from urllib.parse import quote

            import requests

            os.umask(0o077)

            url = os.environ["HD_BASE_URL"].rstrip("/") +
            '/v1/users/conversations/'

            if os.environ.get("HD_QUERY_STRING"): url += "?" +
            os.environ["HD_QUERY_STRING"]

            headers = {"X-Brand-Slug": "hi-doctor", "Accept":
            'application/json'}

            headers["Authorization"] = "Bearer " + os.environ["HD_ACCESS_TOKEN"]

            kwargs = {}

            response = requests.request('GET', url, headers=headers, timeout=30,
            allow_redirects=False, **kwargs)

            Path(os.environ["HD_RESPONSE_FILE"]).write_bytes(response.content)

            Path(os.environ["HD_HEADERS_FILE"]).write_text(json.dumps(dict(response.headers)))

            print(response.status_code)

            print(response.headers.get("Content-Type", ""))
        - lang: JavaScript
          label: fetch
          source: >
            import { readFileSync, writeFileSync } from "node:fs";

            const env = process.env;

            let url = env.HD_BASE_URL.replace(/\/$/, "") +
            "/v1/users/conversations/";

            if (env.HD_QUERY_STRING) url += "?" + env.HD_QUERY_STRING;

            const headers = { "X-Brand-Slug": "hi-doctor", "Accept":
            "application/json" };

            headers.Authorization = "Bearer " + env.HD_ACCESS_TOKEN;

            const options = { method: "GET", headers, redirect: "manual",
            signal: AbortSignal.timeout(30000) };

            const response = await fetch(url, options);

            writeFileSync(env.HD_RESPONSE_FILE, Buffer.from(await
            response.arrayBuffer()), {mode: 0o600});

            writeFileSync(env.HD_HEADERS_FILE,
            JSON.stringify(Object.fromEntries(response.headers)), {mode:
            0o600});

            console.log(response.status);

            console.log(response.headers.get("content-type") ?? "");
components:
  schemas:
    PaginatedConversationList:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          example: 123
          description: Total matching records before pagination.
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
          description: >-
            URL of the next page, or null after the last page. May be null when
            unavailable.
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
          description: >-
            URL of the previous page, or null on the first page. May be null
            when unavailable.
        results:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
          description: Records in this page, in the documented collection order.
    Conversation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            Unique identifier of this resource. Returned by the server; not
            writable.
        user:
          allOf:
            - $ref: '#/components/schemas/ConversationParticipant'
          readOnly: true
          description: User for this conversation. Returned by the server; not writable.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: >-
            Created at timestamp in ISO 8601 format. Returned by the server; not
            writable.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: >-
            Updated at timestamp in ISO 8601 format. Returned by the server; not
            writable.
        is_active:
          type: boolean
          description: Whether active applies to this conversation.
        pinned_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Pinned at timestamp in ISO 8601 format. May be null when
            unavailable.
        last_message:
          readOnly: true
          description: The most recent message. **Null when the thread is empty.**
          anyOf:
            - $ref: '#/components/schemas/ConversationMessage'
            - enum:
                - null
              type: string
              nullable: true
        last_message_created_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: >-
            Last message created at timestamp in ISO 8601 format. Returned by
            the server; not writable. May be null when unavailable.
        last_message_sender_type:
          type: string
          enum:
            - USER
            - ADMIN
            - DOCTOR
            - SYSTEM
            - null
          readOnly: true
          nullable: true
          description: >-
            Last message sender type for this conversation. Returned by the
            server; not writable. May be null when unavailable.
        unread_count:
          type: integer
          readOnly: true
          description: >-
            Unread count for this conversation. Returned by the server; not
            writable.
        subscription_status:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Subscription status for this conversation. Returned by the server;
            not writable. May be null when unavailable.
        translation_target_lang:
          type: string
          nullable: true
          readOnly: true
          description: >-
            Translation target lang for this conversation. Returned by the
            server; not writable. May be null when unavailable.
      required:
        - created_at
        - id
        - last_message
        - last_message_created_at
        - last_message_sender_type
        - subscription_status
        - unread_count
        - updated_at
        - user
    ConversationParticipant:
      oneOf:
        - $ref: '#/components/schemas/ConversationUser'
        - $ref: '#/components/schemas/ConversationPatient'
    ConversationMessage:
      type: object
      description: A single message in the patient's thread with the medical team.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of this resource.
        sender:
          type: string
          format: uuid
          description: Account id of the sender.
        sender_type:
          type: string
          enum:
            - USER
            - ADMIN
            - DOCTOR
            - SYSTEM
          description: >-
            Sender class, including automatic system messages; visibility is
            filtered to the caller.
        content:
          type: string
          nullable: true
          description: Text content of the resource. May be null when unavailable.
        file:
          type: string
          format: uri
          nullable: true
          description: File for this conversation message. May be null when unavailable.
        is_read:
          type: boolean
          description: Whether read applies to this conversation message.
        created_at:
          type: string
          format: date-time
          description: Created at timestamp in ISO 8601 format.
        translation_enabled:
          type: boolean
          description: Whether translation enabled applies to this conversation message.
        translation_default_on:
          type: boolean
          description: Whether translation default on applies to this conversation message.
        source_text:
          type: string
          description: Original message text, emitted only to internal actors.
          nullable: true
        file_name:
          type: string
          description: Display name of the attached file, or null.
          nullable: true
        file_content_type:
          type: string
          description: Attachment media type, or null.
          nullable: true
        event_type:
          type: string
          description: Machine event identifier, or null for an ordinary message.
          nullable: true
        file_available:
          type: boolean
          description: Whether the authorized attachment remains available.
        audience:
          type: string
          description: >-
            Message audience. Patient requests return only patient-visible
            messages.
          enum:
            - patient
            - staff
        event_params:
          description: Structured JSON event parameters; null for an ordinary message.
        translation:
          type: object
          description: Cached translation, present only when available.
          properties:
            translated_text:
              type: string
              description: Translated message text.
            detected_source_lang:
              type: string
              description: Detected language code; null when unknown.
              nullable: true
          required:
            - translated_text
            - detected_source_lang
    ConversationUser:
      type: object
      description: |-
        Read-only nested user for conversation payloads. Carries
        country_of_residence for the doctor inbox (residence flag beside the
        patient name) without touching the registration UserSerializer, whose
        field set doubles as the write contract for sign-up.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            Unique identifier of this resource. Returned by the server; not
            writable.
        email:
          type: string
          format: email
          readOnly: true
          description: Account email address. Returned by the server; not writable.
        first_name:
          type: string
          readOnly: true
          description: >-
            First name for this conversation user. Returned by the server; not
            writable.
        last_name:
          type: string
          readOnly: true
          description: >-
            Last name for this conversation user. Returned by the server; not
            writable.
        country_of_residence:
          type: string
          readOnly: true
          nullable: true
          description: >-
            ISO 3166-1 alpha-3 country code where the patient currently lives.
            Used for EU cross-border prescription dispensing guidance.
      required:
        - country_of_residence
        - email
        - first_name
        - id
        - last_name
    ConversationPatient:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: >-
            Unique identifier of this resource. Returned by the server; not
            writable.
        email:
          type: string
          format: email
          maxLength: 254
          description: Account email address. Maximum 254 characters.
        first_name:
          type: string
          maxLength: 150
          description: First name for this conversation patient. Maximum 150 characters.
        last_name:
          type: string
          maxLength: 150
          description: Last name for this conversation patient. Maximum 150 characters.
        locale:
          allOf:
            - $ref: '#/components/schemas/LocaleEnum'
          description: Preferred email locale.
      required:
        - email
        - id
    LocaleEnum:
      enum:
        - de
        - en
        - es
        - fr
        - it
        - nl
        - pt
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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