Docs
View as Markdown

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.

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 List sessions (no words) scribe.sessions
POST /v1/scribe/sessions Start a dictation or a consultation scribe.sessions
POST /v1/scribe/sessions/words Send words you already have scribe.sessions
POST /v1/scribe/sessions/draft Draft the notes, into your own fields scribe.sessions
POST /v1/scribe/sessions/finish 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

curl "https://api.orkero.app/v1/scribe/sessions?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
  -H "Authorization: Bearer $ORKERO_KEY"

Answer (200)

{
  "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

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"}'

Answer (201)

{
  "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

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}]}'

Answer (200)

{
  "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

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":[{}]}}'

Answer (200)

{
  "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

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"}'

Answer (200)

{
  "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.