Docs
View as Markdown

Scribe quickstart

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

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

1. Start a session

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.

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