Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.healos.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Making Requests

Every call to the Healos External API follows the same pattern. Read this once, and the rest of the API Reference is just details.

​
Request Anatomy

METHOD  {base_url}/{resource}[/{id}]
        X-API-Key: hlsk_your_key_here
        Content-Type: application/json   ← writes only
        { ...json body... }              ← writes only
  • Base URL: https://api.healos.ai/ext-api/v1 (or http://localhost:8787/ext-api/v1 in local development).
  • X-API-Key is required on every request. See Authentication.
  • Content-Type: application/json is required for POST, PATCH, and PUT.

​
Your First Call — List Patients

curl https://api.healos.ai/ext-api/v1/patients \
  -H "X-API-Key: hlsk_your_key_here"
Response: 
{
  "data": [
    {
      "id": "1743552000000",
      "name": "Maria Santos",
      "created_at": "2026-03-15T09:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}
Patient id is a BigInt serialized as a string. Always treat it as an opaque string — don’t parse it as a number, and don’t assume a length.

​
Pagination

List endpoints accept page and limit query parameters. Defaults are page=1 and limit=20. Use meta.total_pages to know when you’ve reached the end. 
curl "https://api.healos.ai/ext-api/v1/patients?page=2&limit=50" \
  -H "X-API-Key: hlsk_your_key_here"

​
Creating a Resource

Write endpoints take a JSON body. The schema for each body is in the API Reference — stick to the documented fields. Extra fields are rejected with a 400 validation error. 
curl https://api.healos.ai/ext-api/v1/patients \
  -H "X-API-Key: hlsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria Santos"}'
Response (201 Created): 
{
  "data": {
    "id": "1743552000000",
    "name": "Maria Santos",
    "created_at": "2026-03-15T09:30:00.000Z",
    "pronouns": null,
    "notes": null,
    "consent": false
  }
}
POST, PATCH, and DELETE require a *:write scope for the resource. A key without it gets a 403. See Authentication → Scopes.

​
Reading One Resource By ID

curl https://api.healos.ai/ext-api/v1/patients/1743552000000 \
  -H "X-API-Key: hlsk_your_key_here"
You can grab a patient’s ID from the Healos web app — it’s shown as a copy-to-clipboard badge next to the patient name in the visit and record headers.
A 404 on a specific ID may mean the resource does not exist or belongs to another user. This is intentional — see Error Handling.

​
External IDs

Patients, appointments, and documents accept an optional external_id on create — a caller-supplied identifier (up to 255 characters) that lets you correlate Healos records with rows in your own system without storing the Healos id. 
curl https://api.healos.ai/ext-api/v1/patients \
  -H "X-API-Key: hlsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria Santos", "external_id": "PARTNER-12345"}'
external_id is unique per organization and immutable once set:
  • Sending external_id on PATCH is silently ignored.
  • Sending a value another record in the same org already uses returns 409 Conflict with the existing record so you can reconcile: 
    {
  "error": "external_id already in use",
  "existing": {
    "id": "481926357104938271",
    "external_id": "PARTNER-12345"
  }
}
For document uploads (multipart/form-data), pass external_id as a form field alongside file and patient_id.

​
Lookup by external_id

List endpoints accept external_id=<value> as a query parameter. The response is the standard list shape — a one-item data array on hit, or 404 on miss — so you can use the same client code as paginated listing. 
curl "https://api.healos.ai/ext-api/v1/patients?external_id=PARTNER-12345" \
  -H "X-API-Key: hlsk_your_key_here"
Documents are scoped to a patient, so the lookup path is /patients/{patientId}/documents?external_id=....

​
Handling Responses

StatusWhat it meansWhere to look
2xxSuccess. Body is { "data": ... }, list endpoints also include meta.—
400Validation error. Body includes a details map of field errors.Error Handling
401Missing, invalid, expired, or revoked key.Authentication
403Key is valid but lacks the required scope.Authentication → Scopes
404Resource not found (or not yours).Error Handling
429Rate limit exceeded. Honor the Retry-After header.Rate Limiting
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset so you can pace yourself without waiting for a 429.

​
Next Steps

API Reference

Full endpoint listing with request and response schemas

Authentication

API keys, scopes, and security best practices