# Scribe reference

> Dictation and the AI scribe: turn what a clinician says, and with the patient's agreement the conversation in the consulting room, into draft notes for the clinician to check and accept.

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

Dictation and the AI scribe: turn what a 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. Runs in Orkero's own clinical records today; designed here,
not yet offered through the API.

| Request | What it does | Scope |
| --- | --- | --- |
| [`GET /v1/scribe/sessions`](#listscribesessions) | List sessions (no words) | `scribe.sessions` |
| [`POST /v1/scribe/sessions`](#startscribesession) | Start a dictation or a consultation | `scribe.sessions` |
| [`POST /v1/scribe/sessions/words`](#addscribewords) | Send words you already have | `scribe.sessions` |
| [`POST /v1/scribe/sessions/draft`](#draftscribenotes) | Draft the notes, into your own fields | `scribe.sessions` |
| [`POST /v1/scribe/sessions/finish`](#finishscribesession) | Finish, and clear the words at once | `scribe.sessions` |

## List sessions (no words)

`GET /v1/scribe/sessions`

> **Early access.** Designed and published so you can plan against it; not open yet.

For counting and billing: each session's kind, state, minutes and when its words
were cleared. Never a word that was said, and nothing about the patient.

Scope: `scribe.sessions`.

### Query

| Name | Type | Needed | What it is |
| --- | --- | --- | --- |
| `practice_id` | string (uuid) | yes |  |
| `after` | string (uuid) |  |  |
| `limit` | integer |  | Default `50`. From 1 to 100. |

### Example

```bash
curl "https://api.orkero.app/v1/scribe/sessions?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"
```
```typescript
const res = await fetch("https://api.orkero.app/v1/scribe/sessions?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
  },
});
const answer = await res.json();
```
```python
import os, requests

res = requests.get(
    "https://api.orkero.app/v1/scribe/sessions?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
```

### Answer (200)

```json
{
  "ok": true,
  "sessions": [
    {
      "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
      "kind": "dictation",
      "state": "listening",
      "started_at": "2026-11-24T09:00:00+00:00",
      "seconds": 1,
      "keep_words_until": "2026-11-24T09:00:00+00:00",
      "words_cleared_at": "2026-11-24T09:00:00+00:00",
      "stream": {}
    }
  ],
  "has_more": true,
  "next_after": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
  "request_id": "web-000123"
}
```

### Errors

| Status | When |
| --- | --- |
| 401 | `no_such_key`, `key_switched_off`, `key_ended`. |
| 403 | `not_allowed` (the key lacks the scope), `not_your_practice`, `whole_organisation`. |

## Start a dictation or a consultation

`POST /v1/scribe/sessions`

> **Early access.** Designed and published so you can plan against it; not open yet.

`dictation` is one clinician speaking; `consultation` listens to the clinician and
the patient, told apart by speaker, and needs the patient's agreement for this
visit (`consent`), which your system asks for and records before calling.

The answer carries a short-lived address and token for streaming the microphone
(16 kHz, 16-bit mono PCM over a WebSocket), good for one connection. **Audio is
never kept.** Or skip the stream and send words you already have with
`POST /v1/scribe/sessions/words`.

The words heard are kept apart from everything else, only until the session is
finished, and never longer than `keep_words_until` (24 hours at most).

Scope: `scribe.sessions`.

### Body

| Field | Type | Needed | What it is |
| --- | --- | --- | --- |
| `practice_id` | string (uuid) | yes |  |
| `kind` | string | yes | One of `dictation`, `consultation`. |
| `clinician` | string |  | Your own reference for the clinician. Never a name you need not send. 0 to 100 characters. |
| `consent` | object |  | Needed for `consultation`. The patient agreed, for this visit, after being told how it works. |
| `consent.given_by` | string | yes | One of `patient`, `parent`, `guardian`, `carer`. |
| `consent.given_at` | string (date‑time) | yes |  |
| `language` | string |  | Default `en-GB`. |
| `request_id` | string |  | 8 to 100 characters. |

### Example

```bash
curl -X POST "https://api.orkero.app/v1/scribe/sessions" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","kind":"dictation","clinician":"<clinician>","consent":{"given_by":"patient","given_at":"2026-11-24T09:00:00+00:00"},"language":"en-GB","request_id":"web-000123"}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/scribe/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "kind": "dictation",
    "clinician": "<clinician>",
    "consent": {
      "given_by": "patient",
      "given_at": "2026-11-24T09:00:00+00:00"
    },
    "language": "en-GB",
    "request_id": "web-000123"
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/scribe/sessions",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
        "kind": "dictation",
        "clinician": "<clinician>",
        "consent": {
            "given_by": "patient",
            "given_at": "2026-11-24T09:00:00+00:00"
        },
        "language": "en-GB",
        "request_id": "web-000123"
    },
)
answer = res.json()
```

### Answer (201)

```json
{
  "ok": true,
  "session": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "kind": "dictation",
    "state": "listening",
    "started_at": "2026-11-24T09:00:00+00:00",
    "seconds": 1,
    "keep_words_until": "2026-11-24T09:00:00+00:00",
    "words_cleared_at": "2026-11-24T09:00:00+00:00",
    "stream": {
      "url": "<url>",
      "token": "<token>",
      "expires_at": "2026-11-24T09:00:00+00:00",
      "format": "<format>"
    }
  },
  "request_id": "web-000123"
}
```

### Errors

| Status | When |
| --- | --- |
| 401 | `no_such_key`, `key_switched_off`, `key_ended`. |
| 403 | `not_allowed` (the key lacks the scope), `not_your_practice`, `whole_organisation`. |
| 409 | `booking_off`, `feedback_off`, `time_gone`, `too_late`, `booking_cancelled`, `booking_past`, `voice_off`, `scribe_off`, `no_consent`. |
| 422 | A field is wrong; the message says which and why. `refused` carries words for the person booking. |
| 429 | `too_many_requests`, `too_many_requests_today`, `too_many_wrong_keys`, `booking_limit`, `practice_busy`. |

## Send words you already have

`POST /v1/scribe/sessions/words`

> **Early access.** Designed and published so you can plan against it; not open yet.

For a system with its own speech-to-text: the words of the session, by speaker.
They are kept as streamed words are, and cleared the same way.

Scope: `scribe.sessions`.

### Body

| Field | Type | Needed | What it is |
| --- | --- | --- | --- |
| `session_id` | string (uuid) | yes |  |
| `segments` | array of object | yes |  |

### Example

```bash
curl -X POST "https://api.orkero.app/v1/scribe/sessions/words" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","segments":[{"speaker":"<speaker>","text":"<text>","start_ms":1,"end_ms":1}]}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/scribe/sessions/words", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "session_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "segments": [
      {
        "speaker": "<speaker>",
        "text": "<text>",
        "start_ms": 1,
        "end_ms": 1
      }
    ]
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/scribe/sessions/words",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "session_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
        "segments": [
            {
                "speaker": "<speaker>",
                "text": "<text>",
                "start_ms": 1,
                "end_ms": 1
            }
        ]
    },
)
answer = res.json()
```

### Answer (200)

```json
{
  "ok": true,
  "session": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "kind": "dictation",
    "state": "listening",
    "started_at": "2026-11-24T09:00:00+00:00",
    "seconds": 1,
    "keep_words_until": "2026-11-24T09:00:00+00:00",
    "words_cleared_at": "2026-11-24T09:00:00+00:00",
    "stream": {
      "url": "<url>",
      "token": "<token>",
      "expires_at": "2026-11-24T09:00:00+00:00",
      "format": "<format>"
    }
  },
  "request_id": "web-000123"
}
```

### Errors

| Status | When |
| --- | --- |
| 401 | `no_such_key`, `key_switched_off`, `key_ended`. |
| 403 | `not_allowed` (the key lacks the scope), `not_your_practice`, `whole_organisation`. |
| 404 | `no_such_visit`, `no_such_booking`, `no_such_line`, `no_such_session`. |
| 410 | `words_gone`: the session was finished, or its keeping time has passed. |
| 422 | A field is wrong; the message says which and why. `refused` carries words for the person booking. |

## Draft the notes, into your own fields

`POST /v1/scribe/sessions/draft`

> **Early access.** Designed and published so you can plan against it; not open yet.

You describe the record's sections and fields (`template`); the draft fills them
from what was said, each value with the words it came from.

**Every proposal is checked before you see it**, and anything that fails is left
out and listed with why: the source words must be in what was said; every number
must have been said; a value for one eye must not be the other eye's; a choice must
be one you offered; and nothing may name a diagnosis, referral or treatment that
was not said. Nothing is saved anywhere: the clinician checks each line, and your
system saves what they accept.

Scope: `scribe.sessions`.

### Body

| Field | Type | Needed | What it is |
| --- | --- | --- | --- |
| `session_id` | string (uuid) | yes |  |
| `template` | object | yes |  |
| `template.sections` | array of object | yes |  |

### Example

```bash
curl -X POST "https://api.orkero.app/v1/scribe/sessions/draft" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","template":{"sections":[{}]}}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/scribe/sessions/draft", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "session_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "template": {
      "sections": [
        {}
      ]
    }
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/scribe/sessions/draft",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "session_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
        "template": {
            "sections": [
                {}
            ]
        }
    },
)
answer = res.json()
```

### Answer (200)

```json
{
  "ok": true,
  "session": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "kind": "dictation",
    "state": "listening",
    "started_at": "2026-11-24T09:00:00+00:00",
    "seconds": 1,
    "keep_words_until": "2026-11-24T09:00:00+00:00",
    "words_cleared_at": "2026-11-24T09:00:00+00:00",
    "stream": {
      "url": "<url>",
      "token": "<token>",
      "expires_at": "2026-11-24T09:00:00+00:00",
      "format": "<format>"
    }
  },
  "proposals": [
    {
      "section": "<section>",
      "field": "<field>",
      "eye": "right",
      "value": "<value>",
      "source": "<source>"
    }
  ],
  "left_out": [
    {
      "section": "<section>",
      "field": "<field>",
      "value": "<value>",
      "why": "not_said"
    }
  ],
  "not_written": [
    "<not_written>"
  ],
  "request_id": "web-000123"
}
```

### Errors

| Status | When |
| --- | --- |
| 401 | `no_such_key`, `key_switched_off`, `key_ended`. |
| 403 | `not_allowed` (the key lacks the scope), `not_your_practice`, `whole_organisation`. |
| 404 | `no_such_visit`, `no_such_booking`, `no_such_line`, `no_such_session`. |
| 410 | `words_gone`: the session was finished, or its keeping time has passed. |
| 422 | A field is wrong; the message says which and why. `refused` carries words for the person booking. |
| 429 | `too_many_requests`, `too_many_requests_today`, `too_many_wrong_keys`, `booking_limit`, `practice_busy`. |

## Finish, and clear the words at once

`POST /v1/scribe/sessions/finish`

> **Early access.** Designed and published so you can plan against it; not open yet.

Call this once the clinician has checked the draft, or to drop a session (the
patient changed their mind). The words and the draft are cleared there and then;
only the counts stay.

Scope: `scribe.sessions`.

### Body

| Field | Type | Needed | What it is |
| --- | --- | --- | --- |
| `session_id` | string (uuid) | yes |  |
| `outcome` | string | yes | `checked`: the clinician went through the draft. `discarded`: drop it (the patient withdrew, say). One of `checked`, `discarded`. |

### Example

```bash
curl -X POST "https://api.orkero.app/v1/scribe/sessions/finish" \
  -H "Authorization: Bearer $ORKERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","outcome":"checked"}'
```
```typescript
const res = await fetch("https://api.orkero.app/v1/scribe/sessions/finish", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORKERO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "session_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "outcome": "checked"
  }),
});
const answer = await res.json();
```
```python
import os, requests

res = requests.post(
    "https://api.orkero.app/v1/scribe/sessions/finish",
    headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
    json={
        "session_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
        "outcome": "checked"
    },
)
answer = res.json()
```

### Answer (200)

```json
{
  "ok": true,
  "session": {
    "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
    "kind": "dictation",
    "state": "listening",
    "started_at": "2026-11-24T09:00:00+00:00",
    "seconds": 1,
    "keep_words_until": "2026-11-24T09:00:00+00:00",
    "words_cleared_at": "2026-11-24T09:00:00+00:00",
    "stream": {
      "url": "<url>",
      "token": "<token>",
      "expires_at": "2026-11-24T09:00:00+00:00",
      "format": "<format>"
    }
  },
  "request_id": "web-000123"
}
```

### Errors

| Status | When |
| --- | --- |
| 401 | `no_such_key`, `key_switched_off`, `key_ended`. |
| 403 | `not_allowed` (the key lacks the scope), `not_your_practice`, `whole_organisation`. |
| 404 | `no_such_visit`, `no_such_booking`, `no_such_line`, `no_such_session`. |
