# Scribe quickstart

> Turn dictation, or the conversation in the consulting room, into checked draft notes. In early access.

Source: https://docs.orkero.app/quickstart/scribe

> **Early access.** Dictation and the AI scribe run in Orkero's own clinical records today.
> The API below is designed and published so you can plan against it; it is not open yet.
> [Ask for early access](/early-access) to be told first.

**What it is for.** It turns what the clinician says, and with the patient's agreement the
conversation in the consulting room, into draft notes for the clinician to check and accept.
It does not diagnose, suggest a diagnosis or recommend treatment. Those words are its
intended purpose, and everything below is built to keep to them.

## The rules it keeps

- **Drafts only.** Nothing is saved to a record by Orkero: the clinician checks each line and
  your system saves what they accept.
- **Every proposal is checked** before you see it. The words it came from must have been
  said; every number must have been said; a right-eye value must not be the left eye's; a
  choice must be one you offered; and nothing may name a diagnosis, referral or treatment
  that was not said. Anything that fails is left out and listed with why.
- **Audio is never kept.** The words heard are kept apart from everything else, cleared the
  moment you finish the session, and never kept longer than 24 hours.
- **A consultation needs the patient's agreement for that visit**, asked by your system
  before you start. Dictation (the clinician alone) does not.

## 1. Start a session

```bash
curl https://api.orkero.app/v1/scribe/sessions \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "practice_id": "'$PRACTICE'",
    "kind": "consultation",
    "consent": { "given_by": "patient", "given_at": "2026-12-01T10:02:00Z" }
  }'
```

The answer has `session.stream`: an address and token for one WebSocket connection. Stream
the microphone to it as 16 kHz, 16-bit mono PCM. Already have your own speech-to-text? Send
the words instead with `POST /v1/scribe/sessions/words`.

## 2. Ask for the draft, in your own fields

Describe your record's sections and fields; the draft fills them.

```bash
curl https://api.orkero.app/v1/scribe/sessions/draft \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "'$SESSION'",
    "template": { "sections": [
      { "key": "history", "label": "History and symptoms", "fields": [
        { "key": "reason", "label": "Reason for visit", "kind": "text" }
      ]},
      { "key": "pressures", "label": "Pressures", "fields": [
        { "key": "iop", "label": "Pressure", "kind": "per_eye", "unit": "mmHg" }
      ]}
    ]}
  }'
```

Each item in `proposals` has its value and the words it came from (`source`), for the
clinician to accept or leave out. `left_out` lists what the check refused and why.

## 3. Finish

`POST /v1/scribe/sessions/finish` with `outcome` `checked` (or `discarded` if the patient
changed their mind) clears the words and the draft there and then.

## Events

`scribe.draft_ready` and `scribe.words_cleared` by [webhook](/webhooks). Neither carries a
word that was said.

## Your responsibilities

The practice remains responsible for the record and for its own paperwork: a data
protection impact assessment, telling patients (a notice before anything is recorded), and
its clinical safety records (in England, DCB0160). We will share ours. In the UK, the
MHRA's guidance on ambient voice technology says that transcribing and drafting for a
clinician to check is not by that alone a medical device; suggesting diagnoses or guiding
treatment would be. Rules elsewhere differ: check them before using it outside the UK.

Full detail: [Scribe reference](/reference/scribe).
