Hi-Doctor Docs — online medical care, connected to your AI assistant

The Hi-Doctor API uses JSON Web Tokens. You exchange an email and password for an access token and a refresh token, then send the access token on every subsequent request. The card below is the whole flow written for an AI agent — copy it into a system prompt, or read the annotated version underneath it.

curl -X POST https://api.hi-doctor.ai/v1/users/token/ \
  -H 'Content-Type: application/json' \
  -H 'X-Brand-Slug: hi-doctor' \
  -d '{
    "email": "patient@example.com",
    "password": "your-password"
  }'

{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "is_doctor": false,
  "is_backoffice_admin": false,
  "is_marketer": false
}

The three role flags are always present. For a patient account they are always false — they exist so the web app can route staff sign-ins, and they are not a permission grant. Nothing in this reference becomes available by reading them.

The X-Brand-Slug: hi-doctor header is required on sign-in. Without it the request is rejected.

Response	Meaning
`401` `code: "invalid_credentials"`	Wrong email or password, or the account is not yet verified
`403` `code: "user_inactive"`	The account is disabled
`400` `code: "google_account"`	Created with Google sign-in, so it has no password

Repeated failures are rate limited.

A 401 on sign-in is deliberately non-specific — it does not tell you whether the address exists. Do not present it to a user as “no such account”.Sending the request without X-Brand-Slug also returns the same 401, so a missing header looks exactly like a wrong password. If sign-in fails unexpectedly, check the header before assuming the credentials are wrong.

2. Call an endpoint

Send the access token as a bearer token:

curl https://api.hi-doctor.ai/v1/users/profile/me/ \
  -H 'Authorization: Bearer <access token>'

Every endpoint in this reference is scoped to the authenticated account. You can only ever read or write your own data — there is no patient or user identifier to pass, and supplying another account’s record id returns 404.

3. Refresh the access token

Access tokens are short-lived. When one expires, exchange the refresh token:

curl -X POST https://api.hi-doctor.ai/v1/users/token/refresh/ \
  -H 'Content-Type: application/json' \
  -d '{ "refresh": "<refresh token>" }'

Errors

Errors are JSON, but there are five different envelopes depending on which layer refused the request. The message key is error on the auth endpoints and detail elsewhere — and neither is present on the most common failure of all, field validation, which returns an object keyed by field name:

Field validation — no detail, no code

{ "email": ["This field is required."], "password": ["This field is required."] }

Sign-in and registration

{ "error": "Invalid credentials", "code": "invalid_credentials" }

Token failures

{ "detail": "Given token not valid for any token type", "code": "token_not_valid" }

Branch on code or error_name where present — those are stable. The prose in error and detail is written for humans and may change.

Errors has all five envelopes, every status code, and the correct client response to each. Read it before writing your error handling — reading only detail loses the message on most validation failures.

Prefer the MCP connector

If you are building an AI assistant rather than a direct integration, use the MCP connector instead. It handles OAuth, scoping and permissions for you, and never exposes the patient’s password to your application.

​1. Sign in

​Sign-in failures

​2. Call an endpoint

​3. Refresh the access token

​Errors

​Prefer the MCP connector

1. Sign in

Sign-in failures

2. Call an endpoint

3. Refresh the access token

Errors

Prefer the MCP connector