POST /v1/users/token/, and read the profile with the access token. Nothing here submits a consultation, pays or changes data.
Last reviewed: 2026-11-04
An AI assistant acting for a patient should not follow this page. It uses the agent quickstart, where sign-in happens on hi-doctor.ai through the MCP connector.
What do you need before the first call?
- A patient account that has completed sign-up and email verification, used with that patient’s consent.
- A server-side application that can keep secrets. The patient types their password into your application, never into a chat or a model prompt.
- The API origin,
https://api.hi-doctor.ai. To check that it is reachable, callGET /v1/system/healthcheck/; the root URL returns404by design.
How do you make the first authenticated read?
1
Set the API origin
Configure
HD_BASE_URL=https://api.hi-doctor.ai explicitly and refuse any other origin before you attach a token.2
Sign the patient in
Send
POST /v1/users/token/ with Content-Type: application/json, X-Brand-Slug: hi-doctor and a JSON object containing email and password. Build the JSON with your client library, never by interpolating credentials into a shell command.3
Store the tokens securely
A
200 response contains access and refresh. Keep them in secure server-side storage and supply the access token to your code as HD_ACCESS_TOKEN. Never log them.4
Read the profile
Call
GET /v1/users/profile/me/ with Authorization: Bearer and the access token, plus X-Brand-Slug: hi-doctor. The examples below do exactly this.401 with code: "invalid_credentials". While the emailed verification code is still valid, sign-in with the registered password returns 401 with code: "verification_required"; once the code has expired the same request returns invalid_credentials. A Google-only account returns 401 with code: "google_account". Authentication covers every sign-in failure and token refresh.
Read your own profile
SendX-Brand-Slug: hi-doctor on every request. It grants no permissions. A REST access token is not an MCP token.
Each example is independent and performs one read. GET has no body; Accept: application/json requests JSON. For endpoints with a JSON body, also send Content-Type: application/json.
200 with one account object. 401 requires authentication recovery; it is not evidence that the patient has no account. The error guide explains recovery without logging raw response bodies.
How do lists work?
REST does not have a universal cursor envelope. Consultations, categories and most collections returncount, next, previous, results with limit/offset pagination. The default is 50 rows, maximum 200 on the default paginator. Journal and adverse-event lists have no documented maximum; request a small page. Orders and documents return arrays; pending subscription choices use a pending array.
Follow next until null. Before attaching a bearer token, require the same HTTPS origin and expected collection path, reject credentials/fragments in the URL, and disable redirects. Keep filters and ordering unchanged; cap page count, detect repeated URLs and deduplicate records by ID because offset pages can shift.
MCP list tools have their own schemas and concise fields (total_count, has_more, next_offset); do not assume the REST envelope applies. See pagination and MCP workflows.
Frequently asked questions
Can I test the API without a patient account?
Only the public endpoints. The health check, questionnaire categories and questionnaire schemas need no token; everything that reads or changes patient data needs a verified patient account and its access token.How long does an access token last?
An access token lasts one day and a refresh token 30 days. Refresh the access token as described in Authentication.Why does sign-in return 401 for a new account?
While the emailed code is still valid, password sign-in returns 401 with the verification required code; after the code expires it returns 401 with the invalid credentials code. Finish sign-up and email verification first.Can I paste a token into an AI chat to test it?
No. Never paste passwords, verification codes or tokens into an AI chat. An assistant should use the MCP connector instead.Does this quickstart change any data?
No. Every example is a read. Submitting a questionnaire, paying and sending messages are covered in the guides linked under Next steps.Next steps
- Answer a questionnaire: Ask one question at a time while Hi Doctor applies the branching and validation.
- Safe retries: Retry a timed-out write without doing it twice, using Idempotency-Key.
- Uploads and downloads: Upload photos and documents, and save PDFs safely.
- API changelog: What changed in the patient REST API, and when.