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

# Clinical Notes

> Read and bulk-export clinical notes, with transcript and patient context

# Clinical Notes

The notes endpoints let you pull clinical notes out of Healos — one at a time,
by session, as a filtered list, or as a bulk export. Every note carries its
medical codes, and you can request the session transcript and patient context
alongside it.

All notes endpoints require the `notes:read` scope. Access is scoped to your
organization: you see notes authored by members of your org.

<Note>
  `patient_id` is a BigInt serialized as a string — treat it as an opaque
  string, same as elsewhere in the API. See [Making Requests](/making-requests).
</Note>

## List Notes

Lightweight, paginated list. Use it to discover note IDs; fetch full content
with [Get a Note](#get-a-note) or [Export](#export-notes).

```bash theme={null}
curl "https://api.healos.ai/ext-api/v1/notes?limit=20" \
  -H "X-API-Key: hlsk_your_key_here"
```

```json theme={null}
{
  "data": [
    {
      "id": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e",
      "patient_id": "481926357104938271",
      "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "note_type": "clinical_visit",
      "specialty": "Cardiology",
      "template_id": "7a1c...",
      "template_name": "Follow-Up Patient Visit",
      "created_at": "2026-03-15T09:30:00.000Z",
      "updated_at": "2026-03-15T10:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total_pages": 1 }
}
```

### Filters

Both `GET /notes` and `GET /notes/export` accept the same filters:

| Query param   | Description                                                  |
| ------------- | ------------------------------------------------------------ |
| `patient_id`  | Notes for one patient                                        |
| `session_id`  | Notes for one session                                        |
| `template_id` | Notes generated from a template                              |
| `created_by`  | Notes authored by a specific clinician (must be in your org) |
| `note_type`   | e.g. `clinical_visit`                                        |
| `from`        | Created on/after this date (ISO 8601, e.g. `2026-01-01`)     |
| `to`          | Created on/before this date (ISO 8601)                       |

```bash theme={null}
curl "https://api.healos.ai/ext-api/v1/notes?patient_id=481926357104938271&from=2026-01-01&to=2026-06-30" \
  -H "X-API-Key: hlsk_your_key_here"
```

## Get a Note

Returns the full note — `content`, `problems`, `procedures`, `icd10_codes`,
`cpt_codes` — with the session transcript and patient context embedded by
default.

```bash theme={null}
curl https://api.healos.ai/ext-api/v1/notes/9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e \
  -H "X-API-Key: hlsk_your_key_here"
```

```json theme={null}
{
  "data": {
    "id": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e",
    "patient_id": "481926357104938271",
    "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "note_type": "clinical_visit",
    "specialty": "Cardiology",
    "template_name": "Follow-Up Patient Visit",
    "created_at": "2026-03-15T09:30:00.000Z",
    "content": "Chief complaint: ...",
    "problems": ["Hypertension"],
    "procedures": ["12-lead ECG"],
    "icd10_codes": { "I10": "Essential hypertension" },
    "cpt_codes": { "Office visit": [{ "code": "99213", "description": "Established patient" }] },
    "transcript": {
      "text": "Doctor: ... Patient: ...",
      "summary": "Patient stable on current regimen.",
      "title": "Follow-up visit",
      "status": "completed",
      "session_date": "2026-03-15T09:00:00.000Z",
      "start_time": "2026-03-15T09:00:00.000Z",
      "end_time": "2026-03-15T09:30:00.000Z"
    },
    "patient": {
      "id": "481926357104938271",
      "name": "Maria Santos",
      "pronouns": "she/her",
      "date_of_birth": "1985-04-12",
      "client_history": {
        "medical_history": "...",
        "family_history": "...",
        "social_history": "...",
        "previous_treatment": "..."
      }
    }
  }
}
```

### Controlling embedded blocks

The note body and medical codes are always returned. Control the heavier
embedded blocks with the `include` query param — a comma-separated list of
`transcript` and `patient`. It defaults to both.

```bash theme={null}
# Omit both embedded blocks (note body + codes only)
curl "https://api.healos.ai/ext-api/v1/notes/{noteId}?include=" \
  -H "X-API-Key: hlsk_your_key_here"

# Transcript only
curl "https://api.healos.ai/ext-api/v1/notes/{noteId}?include=transcript" \
  -H "X-API-Key: hlsk_your_key_here"
```

When excluded, `transcript` and `patient` are returned as `null`.

## Notes by Session

Returns every note for a session, plus the session's transcript/summary and the
patient context, in one call. Returns `404` if the session isn't owned by your
organization.

```bash theme={null}
curl https://api.healos.ai/ext-api/v1/sessions/f47ac10b-58cc-4372-a567-0e02b2c3d479/notes \
  -H "X-API-Key: hlsk_your_key_here"
```

```json theme={null}
{
  "data": {
    "session": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "patient_id": "481926357104938271",
      "transcript": { "text": "...", "summary": "...", "title": "Follow-up visit" }
    },
    "patient": { "id": "481926357104938271", "name": "Maria Santos" },
    "notes": [ { "id": "9b2d...", "content": "...", "icd10_codes": {} } ]
  }
}
```

## Export Notes

`GET /notes/export` returns **all** notes matching the [filters](#filters) above
(no pagination), with full content, codes, transcript, and patient context on
each note. Pick the format with `?format=`:

| `format`         | Response                                              | Notes                                                         |
| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| `json` (default) | `{ "data": [...], "meta": { "count", "truncated" } }` | Capped at 1000 notes                                          |
| `csv`            | `text/csv` attachment                                 | Flattened, one row per note. Capped at 1000 notes             |
| `ndjson`         | `application/x-ndjson` stream                         | One JSON note per line. **No cap** — use this for large pulls |

```bash theme={null}
# JSON (default), filtered to one patient
curl "https://api.healos.ai/ext-api/v1/notes/export?patient_id=481926357104938271" \
  -H "X-API-Key: hlsk_your_key_here"

# CSV download
curl "https://api.healos.ai/ext-api/v1/notes/export?format=csv&from=2026-01-01" \
  -H "X-API-Key: hlsk_your_key_here" -o notes.csv

# NDJSON stream (recommended for full exports)
curl "https://api.healos.ai/ext-api/v1/notes/export?format=ndjson" \
  -H "X-API-Key: hlsk_your_key_here" -o notes.ndjson
```

<Warning>
  `json` and `csv` are capped at **1000 notes**. When the result is capped,
  `json` sets `meta.truncated: true` and `csv` sets the `X-Result-Truncated`
  header. To pull more than 1000 notes, narrow the date range with `from`/`to`,
  or use `format=ndjson`, which streams the full set with no cap.
</Warning>

The CSV columns are: `note_id`, `patient_id`, `patient_name`, `session_id`,
`session_date`, `note_type`, `specialty`, `created_at`, `problems`,
`procedures`, `icd10_codes`, `cpt_codes`, `content`, `transcript`. Array and
code fields are flattened into a single cell.