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"
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();
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)
{
"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"}'
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();
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)
{
"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}]}'
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();
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)
{
"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":[{}]}}'
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();
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)
{
"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"}'
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();
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)
{
"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. |