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

# Quickstart

> Check your key, create a fake patient, generate a note and clean up, in about five minutes

This quickstart makes six calls with **made-up data**: it checks your key,
creates a fake patient, writes a short note for them, reads it back and then
deletes the patient. Run it in a [test organization](https://docs.healos.ai/test-mode.md), not in the
organization that holds your real patients.

> [!WARNING]
>
> Step 4 generates a real note and uses **one Scribe session** from the
> organization's plan. Every other step is free.

## Before you start

1. An org admin opens **Account Settings → API Keys** at
   [app.healos.ai/account-settings](https://app.healos.ai/account-settings) in
   the test organization and creates a key with these scopes:
   `patients:read`, `patients:write`, `notes:read`, `notes:write`.
2. Copy the key (it starts with `hlsk_` and is shown only once) and keep it in
   an environment variable, not in your code:

```bash theme={null}
export HEALOS_API_KEY="hlsk_..."
export HEALOS="https://api.healos.ai/ext-api/v1"
```

## Steps

**1. Check which organization the key acts in**

```bash theme={null}
curl "$HEALOS/me" -H "X-API-Key: $HEALOS_API_KEY"
```

**Expect** `200` with `data.org.name` set to your **test** organization and
the four scopes above. If it names your live organization, stop and create
a key in the test organization instead.

**2. Create a fake patient**

```bash theme={null}
curl -X POST "$HEALOS/patients" \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Testy",
    "last_name": "Quickstart",
    "date_of_birth": "1970-01-01",
    "phone": "+12025550123",
    "external_id": "quickstart-001"
  }'
```

**Expect** `201` with the new patient in `data`. Copy `data.id` (a numeric
string) into `PATIENT_ID`:

```bash theme={null}
export PATIENT_ID="<data.id from the response>"
```

Running this again returns `409` with `existing.id`, because
`external_id` must be unique in the organization. Use that id.

**3. Find the patient by your own id**

```bash theme={null}
curl "$HEALOS/patients?external_id=quickstart-001" -H "X-API-Key: $HEALOS_API_KEY"
```

**Expect** `200` with a one-item `data` array. This is how you look up
records without storing HealOS ids.

**4. Generate a note from text**

```bash theme={null}
curl -X POST "$HEALOS/notes/from-text" \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"patient_id\": \"$PATIENT_ID\",
    \"text\": \"Test visit with made-up details. Knee pain for two weeks, worse on stairs. No swelling. Plan: physiotherapy, follow up in 4 weeks.\"
  }"
```

**Expect** `202` with `data.session_id` and `data.status: "queued"`. Copy
the session id:

```bash theme={null}
export SESSION_ID="<data.session_id from the response>"
```

**5. Read the note**

```bash theme={null}
curl "$HEALOS/sessions/$SESSION_ID/notes" -H "X-API-Key: $HEALOS_API_KEY"
```

**Expect** `200`. `data.notes` is empty while the note is being written and
holds the note within about a minute. Repeat the call every 10 seconds
until it appears. In production, use a `NOTE_CREATED`
[webhook](https://docs.healos.ai/webhooks.md) instead of polling.

**6. Clean up**

```bash theme={null}
curl -X DELETE "$HEALOS/patients/$PATIENT_ID" -H "X-API-Key: $HEALOS_API_KEY"
```

**Expect** `200` with `{ "success": true }`. This permanently deletes the
fake patient with its session and note.

## Expected outcomes

| Step | Expected result | If you see something else |
| - | - | - |
| 1. `GET /me` | `200`, your test organization | `401`: the key is wrong, expired or revoked |
| 2. Create patient | `201` | `409`: already created; use `existing.id`. `403`: the key lacks `patients:write` |
| 3. Look up by `external_id` | `200`, one patient | `404`: the `external_id` doesn't match |
| 4. Generate note | `202`, `status: "queued"` | `402`: no Scribe sessions left. `409`: a request for this patient is being submitted right now. Don't resend after a `202`; each call creates a new note |
| 5. Read note | `200`, one note after about a minute | Empty `notes` for over 5 minutes: contact support with the `session_id` |
| 6. Delete patient | `200`, `success: true` | `404`: already deleted |

## The same flow as a script

The same six calls in JavaScript and Python. Both read the key from the
`HEALOS_API_KEY` environment variable and use only made-up data.

* **JavaScript:** save as `quickstart.mjs` and run it with Node.js 18 or later:
  `HEALOS_API_KEY=hlsk_... node quickstart.mjs`.
* **Python:** install [requests](https://pypi.org/project/requests/)
  (`pip install requests`), save as `quickstart.py` and run it with Python 3.8
  or later: `HEALOS_API_KEY=hlsk_... python quickstart.py`.

```javascript quickstart.mjs theme={null}
const BASE = "https://api.healos.ai/ext-api/v1";
const headers = {
  "X-API-Key": process.env.HEALOS_API_KEY,
  "Content-Type": "application/json",
};

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok && res.status !== 409) {
    throw new Error(`${method} ${path} -> ${res.status}: ${json.error}`);
  }
  return { status: res.status, json };
}

const me = await call("GET", "/me");
console.log("Organization:", me.json.data.org.name);

const created = await call("POST", "/patients", {
  first_name: "Testy",
  last_name: "Quickstart",
  date_of_birth: "1970-01-01",
  external_id: "quickstart-001",
});
const patientId =
  created.status === 409 ? created.json.existing.id : created.json.data.id;

const queued = await call("POST", "/notes/from-text", {
  patient_id: patientId,
  text: "Test visit with made-up details. Knee pain for two weeks. Plan: physiotherapy.",
});
const sessionId = queued.json.data.session_id;

let notes = [];
for (let i = 0; i < 30 && notes.length === 0; i++) {
  await new Promise((r) => setTimeout(r, 10_000));
  notes = (await call("GET", `/sessions/${sessionId}/notes`)).json.data.notes;
}
console.log(notes.length ? notes[0].content : "Note not ready yet");

await call("DELETE", `/patients/${patientId}`);
console.log("Deleted the test patient.");
```

```python quickstart.py theme={null}
import os
import time

import requests

BASE = "https://api.healos.ai/ext-api/v1"
http = requests.Session()
http.headers["X-API-Key"] = os.environ["HEALOS_API_KEY"]


def call(method, path, body=None):
    res = http.request(method, BASE + path, json=body, timeout=30)
    data = res.json()
    if not res.ok and res.status_code != 409:
        raise RuntimeError(f"{method} {path} -> {res.status_code}: {data.get('error')}")
    return res.status_code, data


_, me = call("GET", "/me")
print("Organization:", me["data"]["org"]["name"])

status, created = call("POST", "/patients", {
    "first_name": "Testy",
    "last_name": "Quickstart",
    "date_of_birth": "1970-01-01",
    "external_id": "quickstart-001",
})
patient_id = created["existing"]["id"] if status == 409 else created["data"]["id"]

_, queued = call("POST", "/notes/from-text", {
    "patient_id": patient_id,
    "text": "Test visit with made-up details. Knee pain for two weeks. Plan: physiotherapy.",
})
session_id = queued["data"]["session_id"]

notes = []
for _ in range(30):
    time.sleep(10)
    _, body = call("GET", f"/sessions/{session_id}/notes")
    notes = body["data"]["notes"]
    if notes:
        break
print(notes[0]["content"] if notes else "Note not ready yet")

call("DELETE", f"/patients/{patient_id}")
print("Deleted the test patient.")
```

> [!NOTE]
>
> Both scripts send the note request once and never retry it: each call to
> `POST /notes/from-text` creates a new note and uses a Scribe session. See
> [Going to production](https://docs.healos.ai/going-to-production.md) for safe retries.

## Next steps

> [card] [Recipes](https://docs.healos.ai/recipes/document-to-note.md)
>
> Complete tasks, step by step.

> [card] [Making requests](https://docs.healos.ai/making-requests.md)
>
> Pagination, `external_id` and responses.

> [card] [Error catalog](https://docs.healos.ai/errors.md)
>
> Every status and what to do.


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