Rowan omi.projectz.xyz
API v1

One engine, several clients

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
What a phone gets back This 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
  1. 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.
  2. When the voice finishes, POST ?action=spoken {event_id}. The listening window starts from that moment, not from when the server wrote the line.
  3. 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.
  4. 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.
POST/api/v1/authSign in. {email, password} → {api_key, user}
POST/api/v1/auth?action=signupCreate an account. {email, password, name, timezone?, sample_family?} → 201 {api_key, user, patient?}no auth
GET/api/v1/authWho am I, plus my unread notification count
PATCH/api/v1/authUpdate my profile. {name?, phone?, timezone?}
POST/api/v1/auth?action=rotateGet a new key (the old one stops working)
POST/api/v1/auth?action=revokeSign out everywhere

Patients

You can only see a patient if you have a seat on their care team. An id you cannot see returns 404, not 403, so nobody can probe for ids.
GET/api/v1/patientsEveryone I care for, with my role for each
GET/api/v1/patients?id=NOne patient with care team, who is on duty, devices, and running_run_id
POST/api/v1/patientsAdd a patient. {name, timezone?, self_mode?} → 201. Send {sample: true} to create the sample family instead
PATCH/api/v1/patients?id=NChange settings. {name?, timezone?, voice_name?, listen_seconds?, presence_mode?, presence_band?}primary
DELETE/api/v1/patients?id=NArchive the patientprimary
POST/api/v1/patients?id=N&action=join-codeMake a 6-digit code for the patient's phone. {label?} → {join_code, expires_in_sec}primary
GET/api/v1/patients?id=N&phones=1Phones that have joinedprimary
DELETE/api/v1/patients?id=N&phone=TDisconnect one phoneprimary

Care team and coverage

A coverage window says who is on duty and when. If no window covers a moment, the primary is on duty.
GET/api/v1/care-team?patient_id=NMembers, windows, and who is on duty right now
POST/api/v1/care-teamInvite someone. {patient_id, email, role: caregiver|educator|backup, label?, can_push?, can_edit_own_window?, copy_all?, backup_after_min?, ends_on?} → 201primary
PATCH/api/v1/care-team?id=NChange a seat (same fields as invite, all optional)primary
DELETE/api/v1/care-team?id=NRemove a seatprimary
POST/api/v1/care-team?action=windowAdd a coverage window. {patient_id, member_id, label, weekday_mask, start_time, end_time} → 201primary
DELETE/api/v1/care-team?action=window&id=N&patient_id=NRemove a windowprimary

Routines

The shared library is read-only. Using a library routine copies it into the patient's own list, and edits happen on the copy.
GET/api/v1/routines?patient_id=NLibrary and own routines with step counts. Filter with &category=mornings|mine or &q=text
GET/api/v1/routines?patient_id=N&counts=1How many routines in each category
GET/api/v1/routines?id=N&patient_id=NOne routine with its steps
POST/api/v1/routinesCreate a routine. {patient_id, name, category?, description?, steps?} → 201
POST/api/v1/routines?id=N&action=copyCopy a library routine to the patient. {patient_id} → 201
PATCH/api/v1/routines?id=N&patient_id=NRename or recategorise. {name?, description?, category?}
DELETE/api/v1/routines?id=N&patient_id=NArchive the routine
PUT/api/v1/routines?id=N&patient_id=N&steps=1Replace every step, in order. {steps: [...]}
POST/api/v1/routines?id=N&patient_id=N&steps=1Add a step at the end. {label, prompt?, speech?, short_prompt?, short_speech?, hint?, target_min?, max_min?, repeat_seconds?, confirm_mode?, …} → 201
PATCH/api/v1/routines?id=N&patient_id=N&step=SChange one step
POST/api/v1/routines?id=N&patient_id=N&step=S&action=moveMove a step up or down. {delta: -1|1}
DELETE/api/v1/routines?id=N&patient_id=N&step=SRemove a step

Schedules

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=NAll active schedules
GET/api/v1/schedules?patient_id=N&week=YYYY-MM-DDThe week as a grid
GET/api/v1/schedules?patient_id=N&ready=1Caregiver-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/schedulesPut 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=NChange it, or pause it. {…, starts_by?: rowan|caregiver, status: active|paused}
DELETE/api/v1/schedules?id=N&patient_id=NArchive the schedule
DELETE/api/v1/schedules?id=N&patient_id=N&date=YYYY-MM-DDTake 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=NThe running run, if any, and recent ones
GET/api/v1/runs?id=NFull state: steps with status, current_step, omi_line, omi_hint, listening, pendant, on_duty, clock
GET/api/v1/runs?id=N&events=1The activity log, newest first
POST/api/v1/runsStart a routine now. {patient_id, routine_id, demo?} → 201
POST/api/v1/runsStart 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=pressThe button. Clears the open stepphone or adult
POST/api/v1/runs?id=N&action=heardSomething 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 windowphone or adult
POST/api/v1/runs?id=N&action=spokenThe device finished saying a line. {event_id}. The listening window starts nowphone or adult
POST/api/v1/runs?id=N&action=more_timeThe patient asked for more timephone or adult
POST/api/v1/runs?id=N&action=repeatSay the prompt againphone or adult
POST/api/v1/runs?id=N&action=pushMark the step okay for now (the report says "pushed", not done)caregiver
POST/api/v1/runs?id=N&action=jumpGo 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 stepcaregiver
POST/api/v1/runs?id=N&action=add_timeExtend the step. {minutes?}caregiver
POST/api/v1/runs?id=N&action=stopEnd the runcaregiver
POST/api/v1/runs?id=N&action=tickBring the state up to date (the cron does this every minute)
POST/api/v1/runs?id=N&action=elapseMove 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=claimTurn a join code into a token. {code, label?} → 201 {token, patient}no auth
GET/api/v1/patientEverything the phone shows: patient, run state, pendant, next schedulesphone
POST/api/v1/patient?action=pressThe buttonphone
POST/api/v1/patient?action=heardSomething 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 windowphone
POST/api/v1/patient?action=spokenFinished saying a line. {event_id}phone
POST/api/v1/patient?action=more_timeMore time, pleasephone
POST/api/v1/patient?action=repeatSay it againphone
POST/api/v1/patient?action=startStart 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.
GET/api/v1/devices?patient_id=NThe patient's pendants
POST/api/v1/devicesStart pairing. {patient_id, name} → 201 {pair_code}primary
POST/api/v1/devices?id=N&action=confirmFinish pairing. {code} → {device_token}, shown onceprimary
POST/api/v1/devices?id=N&action=activateMake this the active pendantprimary
POST/api/v1/devices?id=N&action=unpairForget the pendantprimary
POST/api/v1/devices?id=N&action=chimeMake it chime, to find itprimary
PATCH/api/v1/devices?id=N{name?, volume?}primary
GET/api/v1/devices?me=1My status and the run statependant
POST/api/v1/devices?action=buttonThe button was pressed. {press: single|long|double}pendant
POST/api/v1/devices?action=heartbeatStill 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=NMP3 of one of Rowan's lines (server driver only; 501 otherwise)
GET/api/v1/speech?patient_id=NThe voice this patient's devices should use
GET/api/v1/speech?voices=1Voice presets and languages, for a settings screen
PATCH/api/v1/patients?id=NChoose 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=tokenGet a token to broadcast. → {token, rotate_in_sec, report_every_sec}phone or pendant
POST/api/v1/presence?action=reportWhat was heard over the air. {heard: [tokens], beacons: [ids], location?: {lat, lng}} → presence. Every report_every_secphone or pendant
GET/api/v1/presenceCurrent mode and what to do about it: mode, pinned, line, badge, haptic, confirm_by, mic, voice_out, voice_level, awareness, location, placephone or pendant
GET/api/v1/presence?patient_id=NThe same, for a caregiver
PATCH/api/v1/patients?id=NPin 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=beaconA venue creates a quiet-zone beacon. {label} → 201 {beacon_id, policy: quiet}. The venue never learns who is there
GET/api/v1/presence?beacons=1Beacons 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=locateA 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=1Named places with coordinates. Add &patient_id=N as a caregiver
GET/api/v1/presence?journey=1&patient_id=NRecent stays, and unnamed cells that could be given a namecaregiver
POST/api/v1/presence?action=add-placeName a place. {patient_id, name, kind: home|school|care|other, lat?, lng?} → 201. Every past stay there is relabelledprimary
DELETE/api/v1/presence?place=ID&patient_id=NForget a placeprimary
POST/api/v1/presence?action=hereSay 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-consentAgree or withdraw. {agree: bool}primary
POST/api/v1/patients?id=N&action=mec-statusVault state, the write queue, recent writesprimary

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.
GET/api/v1/phrases?patient_id=NLearned phrasesphone or adult
POST/api/v1/phrasesTeach one. {patient_id, kind: wake|done|more_time, text} → 201phone or adult
POST/api/v1/phrases?action=testTry a transcript and see how Rowan would read it. {patient_id, text}
DELETE/api/v1/phrases?id=N&patient_id=NForget oneprimary

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=NThe shared library and the patient's own lines, with the buckets
POST/api/v1/encouragementsAdd an own line. {patient_id, bucket, text} → 201. {name} and {step} are filled inprimary
DELETE/api/v1/encouragements?id=N&patient_id=NRemove an own line (the library is read-only)primary
POST/api/v1/encouragements?action=previewWhat 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=STurn 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/notificationsNewest first, with the unread count. Add ?unread=1 for unread only
POST/api/v1/notifications?id=N&action=readMark it read
POST/api/v1/notifications?id=N&action=ackAcknowledge it. This stops the 5-minute escalation to the primary
POST/api/v1/notifications?action=read_allMark 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=NRoutines that have run
GET/api/v1/reports?patient_id=N&routine_id=RThe weekly report and suggestions. Add &week=YYYY-MM-DD or &demo=1
GET/api/v1/reports?patient_id=N&action=activityWhere 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
POST/api/v1/reports?patient_id=N&routine_id=R&action=applyApply a suggestion. {apply}primary
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.