List medical notifications
List medical notifications using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/notifications/medical |
Authentication · Access policies
Lists your project's medical notifications (heart rate, respiratory rate and other vital-sign alerts), newest first, one page at a time. Medical episodes are decided by Signals; Ovok reads them from Signals, adds the resident context, and never re-derives a clinical value.
Auth: Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant Patient:read, Device:read and Location:read (admins and super admins skip this check).
Scope: The caller's project (from the token), applied on both sides: Signals filters on the resident's project stamp, and Ovok checks each resolved resident against your project.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | "OPEN" | "CLOSED" | No | Only episodes in this state. Both when omitted. |
since | string (ISO 8601 date-time) | No | Only episodes opened at or after this instant. A UTC instant ending in Z. |
acknowledged | string | No | true, 1 or yes (any case) for acknowledged episodes only. Any other value, such as false, for unacknowledged only. Both when omitted. |
patient | string | No | Only this resident's episodes: an Ovok Patient.id, the carehub.patientId a row returns. Maximum 64 characters. It does not widen the project scope. |
codes | string | No | Only these vitals: LOINC codes, comma separated, at most 32, no spaces, for example 8867-4,9279-1. PI is perfusion index. Signals applies the filter. Omit for every medical code. |
limit | integer | No | The page size. Minimum 1, maximum 200, default 50. |
cursor | string | No | The previous page's nextCursor, passed back unchanged. Opaque; maximum 500 characters. |
Behaviour
- One row per episode, not per reading: a run of readings outside the band is one episode. Its
closeReasonvalues are listed in How an episode behaves. - Each row has three blocks.
episodeis the Signals episode with its aggregates.carehubis the resident context Signals does not hold: resident, room and bed, device, zone. Its fields arenullwhen the resident has no device assigned.acknowledgementisnulluntil someone acknowledges the episode. - Use
episode.idwithGET /v1/slim/notifications/medical/{episodeId}to get the full value history. episode.firedBandis the band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from Signals' configuration history at the episode's trigger version. It is not the resident's current band, so editing a threshold does not change past rows.minandmaxare each nullable (a band can be one-sided).firedBandisnullwhen the band cannot be established; that never fails the read.- Filters:
status(OPENorCLOSED, both when omitted),since(episodes opened at or after this ISO 8601 instant),acknowledged(true,1oryesfor acknowledged only; any other value for unacknowledged only; both when omitted). patientnarrows the feed to one resident, by OvokPatient.id(thecarehub.patientIda row returns). It does not change the project scope. A resident who cannot be resolved, or who is in another project, answers 404 rather than an unfiltered page.codesnarrows the feed to these LOINC codes, comma separated, at most 32 (for example8867-4,9279-1). Perfusion index isPI. Signals applies the filter. Out-of-bed is never in this feed. A malformed list fails validation.- Paging:
limitis 1 to 200 (default 50). Pass the previous page'snextCursorascursor. Page untilnextCursorisnull, not until a short page arrives: rows whose resident cannot be resolved into your project are dropped after Signals counted them. Treat the cursor as opaque. noteCountcounts the notes left on each episode. It isnullfor a row whose count could not be established.- A resident with no Signals project stamp matches no project and does not appear.
- When the project's Signals tenant has episodic alerts switched off, the page is empty.
- Out-of-bed is served by
GET /v1/slim/notifications/oob. - Ovok waits up to 5 seconds for Signals. A
503 signals_unavailable(signals_unavailable) means Signals did not answer in time; it is not an empty result. Retry afterretryAfterSec. Under load the read can also be shed with a 503 (live_reads_over_capacity).
Example
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical?status=OPEN&codes=8867-4,9279-1&limit=50' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — A page of medical notifications.
{
"items": [
{
"episode": {
"id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
"code": "8867-4",
"system": "http://loinc.org",
"display": null,
"status": "OPEN",
"openedAt": "2026-10-09T07:40:12.000Z",
"closedAt": null,
"closeReason": null,
"lastSampleAt": "2026-10-09T08:05:12.000Z",
"durationMs": 1500000,
"observationCount": 6,
"firingCount": 6,
"minValue": 118,
"maxValue": 134,
"avgValue": 125.5,
"lastValue": 131,
"peakValue": 134,
"peakAt": "2026-10-09T07:55:12.000Z",
"lastFiringValue": 131,
"lastFiringAt": "2026-10-09T08:05:12.000Z",
"lastObservationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b41",
"firedBand": {
"min": 50,
"max": 110,
"triggerVersion": 2
}
},
"carehub": {
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
"patientName": "demo-resident",
"locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b23",
"locationName": "Room 101",
"room": "101",
"bed": "A",
"floor": "1",
"deviceId": "DEMO-0001",
"deviceMedplumId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b24",
"deviceName": "Demo Bed Sensor",
"organizationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b25",
"organizationName": "Demo Care Home"
},
"acknowledgement": null,
"noteCount": 0
}
],
"nextCursor": "c2FtcGxlLWN1cnNvcg"
}| Field | Type | Description |
|---|---|---|
items | object[] | The page of episodes, newest first. Each element is a row, described below. |
nextCursor | string | null | An opaque cursor for the next page, or null on the last page. Page until it is null, not until a short page arrives. |
Each row has three blocks (episode, carehub, acknowledgement) and a noteCount. A nullable field is always present, as null when it has no value.
| Field | Type | Description |
|---|---|---|
items[].episode | object | The Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band. |
items[].episode.id | string | The episode id. Use it with GET /v1/slim/notifications/medical/{episodeId} and POST /v1/slim/notifications/medical/{episodeId}/ack. |
items[].episode.patientId | string | The resident's id at Signals. It equals carehub.patientId for residents created recently; use carehub.patientId with other Ovok routes. |
items[].episode.code | string | The vital the episode is about: a LOINC code such as 8867-4 (heart rate) or 9279-1 (respiratory rate), or PI for perfusion index. |
items[].episode.system | string | null | The code system of code, for example http://loinc.org. |
items[].episode.display | string | null | Display text for code, when Signals has one. |
items[].episode.status | "OPEN" | "CLOSED" | Whether the episode is still running. |
items[].episode.openedAt | string (ISO 8601 date-time) | When the episode opened. |
items[].episode.closedAt | string (ISO 8601 date-time) | null | When it closed. null while it is open. |
items[].episode.closeReason | "RECOVERED" | "TIMEOUT" | "ACKNOWLEDGED" | "CROSSED" | "THRESHOLD_CHANGED" | "AWAY" | "STALE" | "MANUAL" | null | Why it closed; null while open. See How an episode behaves for each meaning. |
items[].episode.lastSampleAt | string (ISO 8601 date-time) | null | When the newest reading was folded in. On an open episode it shows how fresh the data is. |
items[].episode.durationMs | number | null | The episode length in milliseconds, as Signals reports it. |
items[].episode.observationCount | number | null | How many readings were folded into the episode. |
items[].episode.firingCount | number | null | How many of those readings were outside the band. |
items[].episode.minValue | number | null | The lowest reading in the episode. |
items[].episode.maxValue | number | null | The highest reading in the episode. |
items[].episode.avgValue | number | null | The average reading in the episode. |
items[].episode.lastValue | number | null | The newest reading folded in. On a recovered episode this is the recovery reading. |
items[].episode.peakValue | number | null | The peak reading of the episode. |
items[].episode.peakAt | string (ISO 8601 date-time) | null | When the peak reading was recorded. |
items[].episode.lastFiringValue | number | null | The last reading outside the band. This is the value a closed episode should headline. null for episodes stored before Signals tracked it; use peakValue then. |
items[].episode.lastFiringAt | string (ISO 8601 date-time) | null | When the last reading outside the band was recorded. |
items[].episode.lastObservationId | string | null | The id of the last evaluated reading folded in. On a recovered episode, the reading that closed it. Match it against values[].observationId on the detail route. |
items[].episode.firedBand | object | null | The band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from its configuration history. It is not the resident's current band, so editing a threshold does not change past episodes. null when the band cannot be established; that never fails the read. |
items[].episode.firedBand.min | number | null | The lower limit, or null when the band has no lower limit. |
items[].episode.firedBand.max | number | null | The upper limit, or null when the band has no upper limit. |
items[].episode.firedBand.triggerVersion | number | null | The version of the resident's threshold rule the band belongs to. |
items[].carehub | object | The resident context Signals does not hold. Every field except carehub.patientId is null when the resident has no device assigned or the context could not be read. |
items[].carehub.patientId | string (uuid) | The resident's Ovok Patient.id. Use it for the patient filter and for other Slim routes. |
items[].carehub.patientName | string | null | The resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the first name on file. |
items[].carehub.locationId | string (uuid) | null | The room's Location id. |
items[].carehub.locationName | string | null | The room's name. |
items[].carehub.room | string | null | The room label, from the Location's type codings. |
items[].carehub.bed | string | null | The bed label, from the Location's type codings. |
items[].carehub.floor | string | null | The floor label, from the Location's type codings. |
items[].carehub.deviceId | string | null | The device serial that the Slim device routes use. |
items[].carehub.deviceMedplumId | string (uuid) | null | The device's FHIR Device.id. |
items[].carehub.deviceName | string | null | The device's display name. |
items[].carehub.organizationId | string (uuid) | null | The zone's id. A zone is the device's managing Organization. |
items[].carehub.organizationName | string | null | The zone's name. |
items[].acknowledgement | object | null | null until someone acknowledges the episode. |
items[].acknowledgement.acknowledgedAt | string (ISO 8601 date-time) | When the episode was acknowledged. |
items[].acknowledgement.acknowledgedBy | string | null | Ovok's client id at Signals. It is the same value for every acknowledgement made through Ovok. It is not a person: do not show it as a name. |
items[].acknowledgement.acknowledgedActor | object | null | Who acknowledged. null for acknowledgements made before Ovok sent an actor, and when the session had no profile. |
items[].acknowledgement.acknowledgedActor.reference | string | The caller's profile reference, normally Practitioner/{id}. Admin and service sessions can carry another profile type. |
items[].acknowledgement.acknowledgedActor.display | string | null | The caller's display name, captured when the episode was acknowledged. |
items[].noteCount | integer | null | The number of notes on this episode. null when the count could not be established. |
Errors
| Status | Meaning |
|---|---|
401 | Bearer token is missing, invalid or expired. |
403 | You are not a practitioner, admin or System Owner, you lack Patient:read, Device:read or Location:read, your session has no project, or you cannot access the project. |
404 | The patient filter names a resident who cannot be resolved or is not in your project. |
422 | A query parameter fails validation, for example an unknown status, a since that is not a UTC instant, a codes list that is malformed or longer than 32, a limit outside 1 to 200, or a patient or cursor that is too long. |
503 | Signals did not answer within 5 seconds (error: "signals_unavailable" (signals_unavailable)), or the server shed the read (error: "live_reads_over_capacity" (live_reads_over_capacity)). The body carries retryAfterSec and the Retry-After header carries the same delay in seconds. This is not an empty result: retry after the delay. |
Last updated on