The caregiver's web app, the patient's phone and the pendant all talk to the same server. The routine engine, the rules for what counts as "done", the notifications and the reports live there. A native app does not reimplement any of it. Every state change is one JSON call, and everything the web app can do is on this page.
The basics
Base URL https://omi.projectz.xyz/api/v1. Send JSON, get JSON. Responses look like {"status":"success","data":…} or {"status":"error","error":"…"}.
Three kinds of caller, three headers: X-API-Key for adults, X-Patient-Token for the patient's phone, X-Device-Token for a pendant. The "who" column below says which is expected when it matters.
Status codes: 201 created · 401 not signed in · 403 your role cannot do this · 404 not found, or not yours · 409 conflict (usually "a routine is already running") · 422 bad input.
Timestamps (…_at) are UTC. start_time and end_time are wall-clock in the patient's timezone. weekday_mask bit 0 is Monday.
Every response carries an X-Request-Id header. Quote it when reporting a problem.
What a phone gets backThis is the one call the patient's phone polls. Everything on the screen comes from it.GET /api/v1/patient X-Patient-Token: …
{
"status": "success",
"data": {
"patient": { "id": 1, "name": "Eli", "voice_name": "Rowan", "listen_seconds": 8, … },
"run": {
"status": "running", "progress_label": "Step 3 of 6", "clock": "7:06 AM",
"omi_line": "Time to brush your teeth.",
"omi_hint": "Say \"Rowan, done\" or press your button when you finish.",
"listening": true, "listening_remaining_sec": 6, "pendant": "listening",
"speech": { "event_id": 812, "text": "Time to brush your teeth.", "spoken": false, "audio_url": null,
"voice": { "preset": "warm", "lang": "en-US", "gender": "female", "rate": 0.95, "pitch": 1.0, "device_voice": null, "driver": "browser" } },
"current_step": { "label": "Brush teeth", "status": "waiting", "waiting_sec": 95, "max_min": 8, "confirm_mode": "voice_or_button", "awaiting_second": false, … },
"steps": [ { "label": "Wake up", "status": "done", "elapsed_sec": 40, "cleared_by": "button", "repeats": 0, "ambient_acks": 0 }, … ],
"on_duty": { "name": "Mom", "role": "primary", "window": { "label": "School morning", "start": "6:00 AM", "end": "8:00 AM" } }
},
"pendant": { "name": "Home pendant", "status": "active", "battery_pct": 82 },
"next": [ … ]
}
}
How a phone speaks and listens
Poll GET /api/v1/patient every few seconds. When run.speech.event_id changes, say speech.text (or play audio_url). Show omi_line on screen; it is shorter and may differ from what is spoken.
When the voice finishes, POST ?action=spoken {event_id}. The listening window starts from that moment, not from when the server wrote the line.
Keep the microphone open for listening_remaining_sec. Send what you heard as heard {text, step_id}, with the id of the step you opened the mic for, and close the mic when the patient presses the button. The server decides whether it counts and answers with Rowan's next line.
The button (press) works at any time and needs none of the above.
Signing in
Adults sign in once and keep an API key. Send it as X-API-Key on every call.
Times are wall-clock in the patient's timezone. weekday_mask is a bit field where bit 0 is Monday. The server starts anything that is due, once a minute.
GET
/api/v1/schedules?patient_id=N
All active schedules
GET
/api/v1/schedules?patient_id=N&week=YYYY-MM-DD
The week as a grid
GET
/api/v1/schedules?patient_id=N&ready=1
Caregiver-start routines waiting for a Start, with scheduled_for and waiting: soon (up to 30 min early) | ready (up to 4 h late)
POST
/api/v1/schedules
Put a routine on the calendar. {patient_id, routine_id, start_time, weekday_mask?|on_date?, starts_on?, ends_on?, starts_by?: rowan|caregiver} → 201. "caregiver" = at its time Rowan stays quiet, the on-duty caregiver gets a ready notice, and it waits for a Start
PATCH
/api/v1/schedules?id=N&patient_id=N
Change it, or pause it. {…, starts_by?: rowan|caregiver, status: active|paused}
Take that weekday off the schedule. Returns the schedule; it is archived when no days remain
Runs
A run is a routine in progress. The same state object drives the caregiver's view and the patient's phone. All timing is on the server; clients never keep time.
GET
/api/v1/runs?patient_id=N
The running run, if any, and recent ones
GET
/api/v1/runs?id=N
Full state: steps with status, current_step, omi_line, omi_hint, listening, pendant, on_duty, clock
GET
/api/v1/runs?id=N&events=1
The activity log, newest first
POST
/api/v1/runs
Start a routine now. {patient_id, routine_id, demo?} → 201
POST
/api/v1/runs
Start a waiting caregiver-start schedule. {patient_id, schedule_id} → 201, linked to the schedule; 422 when it is not waiting
POST
/api/v1/runs?id=N&action=press
The button. Clears the open step
phone or adult
POST
/api/v1/runs?id=N&action=heard
Something the patient said. {text, step_id?, tapped?}, or multipart audio when the server speech driver is on. step_id = the step the mic was opened for; if that step has cleared since, it is logged and ignored. tapped = the patient opened the mic on purpose (tap to speak, typed); interpreted even outside the listening window
phone or adult
POST
/api/v1/runs?id=N&action=spoken
The device finished saying a line. {event_id}. The listening window starts now
phone or adult
POST
/api/v1/runs?id=N&action=more_time
The patient asked for more time
phone or adult
POST
/api/v1/runs?id=N&action=repeat
Say the prompt again
phone or adult
POST
/api/v1/runs?id=N&action=push
Mark the step okay for now (the report says "pushed", not done)
caregiver
POST
/api/v1/runs?id=N&action=jump
Go straight to a step. {position}. Ahead: open steps in between are marked skipped (step status "skipped", no time recorded). Back: that step and the ones after it reopen. Rowan relays the move, then prompts the step
caregiver
POST
/api/v1/runs?id=N&action=add_time
Extend the step. {minutes?}
caregiver
POST
/api/v1/runs?id=N&action=stop
End the run
caregiver
POST
/api/v1/runs?id=N&action=tick
Bring the state up to date (the cron does this every minute)
POST
/api/v1/runs?id=N&action=elapse
Move the clock forward. {seconds}. Demo runs only
The patient's phone
The patient never has a password. Their phone enters a 6-digit code once and keeps a token. Send it as X-Patient-Token.
POST
/api/v1/patient?action=claim
Turn a join code into a token. {code, label?} → 201 {token, patient}
no auth
GET
/api/v1/patient
Everything the phone shows: patient, run state, pendant, next schedules
phone
POST
/api/v1/patient?action=press
The button
phone
POST
/api/v1/patient?action=heard
Something the patient said. {text, step_id?, tapped?} or multipart audio. step_id = the step the mic was opened for; if that step has cleared since, it is logged and ignored. tapped = the patient opened the mic on purpose (tap to speak, typed); interpreted even outside the listening window
phone
POST
/api/v1/patient?action=spoken
Finished saying a line. {event_id}
phone
POST
/api/v1/patient?action=more_time
More time, please
phone
POST
/api/v1/patient?action=repeat
Say it again
phone
POST
/api/v1/patient?action=start
Start a routine. {routine_id}. Only when the patient runs their own routines (self mode)
phone
Pendants
A pendant is paired by the primary and then calls with its own token, X-Device-Token. Only one pendant is active at a time; a spare's button press is recorded but ignored.
Finish pairing. {code} → {device_token}, shown once
primary
POST
/api/v1/devices?id=N&action=activate
Make this the active pendant
primary
POST
/api/v1/devices?id=N&action=unpair
Forget the pendant
primary
POST
/api/v1/devices?id=N&action=chime
Make it chime, to find it
primary
PATCH
/api/v1/devices?id=N
{name?, volume?}
primary
GET
/api/v1/devices?me=1
My status and the run state
pendant
POST
/api/v1/devices?action=button
The button was pressed. {press: single|long|double}
pendant
POST
/api/v1/devices?action=heartbeat
Still here. {battery_pct}
pendant
Speech
Every run state includes a speech object: {event_id, text, spoken, voice, audio_url}. With the browser driver the client speaks the text itself using the voice settings. With the api driver it plays audio_url instead, and can upload audio to heard.
GET
/api/v1/speech?event=N
MP3 of one of Rowan's lines (server driver only; 501 otherwise)
GET
/api/v1/speech?patient_id=N
The voice this patient's devices should use
GET
/api/v1/speech?voices=1
Voice presets and languages, for a settings screen
PATCH
/api/v1/patients?id=N
Choose the voice. {voice_preset, voice_lang, voice_device?, voice_rate?, voice_pitch?}
primary
Nearby: other companions in the room
The phone broadcasts a random token that changes every few minutes and reports the tokens it hears. The server works out who is sharing a room and adjusts how Rowan listens: taps instead of voice, turns instead of talking over each other, silence in a quiet place. See the Nearby page for the reasoning.
POST
/api/v1/presence?action=token
Get a token to broadcast. → {token, rotate_in_sec, report_every_sec}
phone or pendant
POST
/api/v1/presence?action=report
What was heard over the air. {heard: [tokens], beacons: [ids], location?: {lat, lng}} → presence. Every report_every_sec
phone or pendant
GET
/api/v1/presence
Current mode and what to do about it: mode, pinned, line, badge, haptic, confirm_by, mic, voice_out, voice_level, awareness, location, place
phone or pendant
GET
/api/v1/presence?patient_id=N
The same, for a caregiver
PATCH
/api/v1/patients?id=N
Pin the mode or set the priority band. {presence_mode: auto|solo|co_present|quiet, presence_band: low|standard|care}
primary
POST
/api/v1/presence?action=beacon
A venue creates a quiet-zone beacon. {label} → 201 {beacon_id, policy: quiet}. The venue never learns who is there
GET
/api/v1/presence?beacons=1
Beacons I have created
Location
Coordinates are rounded to a 3-decimal cell (about 100 m) the moment they arrive; the exact fix is never stored. Staying in one cell for 90 seconds counts as being somewhere, and only then does Rowan look for a name: a place the caregiver named within 150 m, or "unnamed". Each arrival and departure is written to the patient's MeCentral journey when that is on. Two companions in the same cell are treated as nearby even without Bluetooth, and Rowan drops to a whisper.
POST
/api/v1/presence?action=locate
A location fix. {lat, lng, heard?, beacons?} → presence, with location {cell, static_sec, settled, settle_in_sec} and place {name, kind, event, at, label, unnamed}
phone or pendant
GET
/api/v1/presence?places=1
Named places with coordinates. Add &patient_id=N as a caregiver
GET
/api/v1/presence?journey=1&patient_id=N
Recent stays, and unnamed cells that could be given a name
caregiver
POST
/api/v1/presence?action=add-place
Name a place. {patient_id, name, kind: home|school|care|other, lat?, lng?} → 201. Every past stay there is relabelled
primary
DELETE
/api/v1/presence?place=ID&patient_id=N
Forget a place
primary
POST
/api/v1/presence?action=here
Say where the patient is by hand. {patient_id, place_id} → presence. The phone may call it too, without patient_id
Works with MeCentral
With the primary's consent, the patient's nearby settings (pin, band, broadcast token, mode history) and their journey are kept in the patient's own MeCentral vault rather than only in Rowan. Never for the sample family.
POST
/api/v1/patients?id=N&action=mec-consent
Agree or withdraw. {agree: bool}
primary
POST
/api/v1/patients?id=N&action=mec-status
Vault state, the write queue, recent writes
primary
Phrases: what the patient actually says
Speech recognisers only return words they know, so an unusual name or phrase comes out differently on every device. Rowan learns how this patient's words arrive. A taught "done" phrase counts on its own; a bare "yes" can never be taught as done.
Try a transcript and see how Rowan would read it. {patient_id, text}
DELETE
/api/v1/phrases?id=N&patient_id=N
Forget one
primary
Encouragement
When the patient finishes a step themselves (never after a push), Rowan says a line of praise before the next step, chosen by how the same step went the last few times: first, improved, on_track, faster, slipped or keep_trying. Finishing within the step's target is on time. Per step, praise (on by default) and praise_window (how many earlier times to compare with, default 3) are set on the routine step; the chosen bucket is praise_bucket on each run step.
GET
/api/v1/encouragements?patient_id=N
The shared library and the patient's own lines, with the buckets
POST
/api/v1/encouragements
Add an own line. {patient_id, bucket, text} → 201. {name} and {step} are filled in
primary
DELETE
/api/v1/encouragements?id=N&patient_id=N
Remove an own line (the library is read-only)
primary
POST
/api/v1/encouragements?action=preview
What Rowan would say if the step were finished now. {patient_id, label, elapsed_sec, target_min, window?} → {bucket, on_time, history, text}
PATCH
/api/v1/routines?id=N&patient_id=N&step=S
Turn it off or change the lookback for one step. {praise: bool, praise_window: 1-10}
Notifications
Sent to whoever is on duty. The app polls for them; push delivery is not built yet.
GET
/api/v1/notifications
Newest first, with the unread count. Add ?unread=1 for unread only
POST
/api/v1/notifications?id=N&action=read
Mark it read
POST
/api/v1/notifications?id=N&action=ack
Acknowledge it. This stops the 5-minute escalation to the primary
POST
/api/v1/notifications?action=read_all
Mark everything read
Reports
For each step: how long from prompt to done, how many repeats, how many replies Rowan did not count, and who cleared it. Rowan also suggests changes, which can be applied in one call.
GET
/api/v1/reports?patient_id=N
Routines that have run
GET
/api/v1/reports?patient_id=N&routine_id=R
The weekly report and suggestions. Add &week=YYYY-MM-DD or &demo=1
GET
/api/v1/reports?patient_id=N&action=activity
Where the reports are: finished runs per day and per week for a calendar, the latest week with runs, and the nearest earlier and later weeks with runs. Add &routine_id=R, &week=YYYY-MM-DD, &demo=1 or &weeks=26
Not in this proof of conceptPush notifications: the rows exist, but delivery is polling plus email. Server-side speech: built but switched off until a vendor is chosen, so each device speaks and listens itself. MeCentral: only the nearby settings and the journey are written to the patient's vault; runs and reports still live in Rowan alone.