Observations
Submitting readings. This is the hot path: one POST per reading (or a batch), judged by the patient's triggers in force (its own over its home's) before the response returns unless the tenant is in async mode.
| Operation | Endpoint |
|---|---|
| Submit a reading by patient refId | POST /api/observation |
| Submit several readings for one patient | POST /api/observation/{patientId}/batch |
| Submit a reading for a patient id | POST /api/observation/{patientId} |
| List a patient's readings | GET /api/observation/{patientId} |
POST /api/observation
/api/observationSubmit a reading by patient refId
The patient is patientRefId in the body, else subject.reference (Patient/<refId>).
The body is a FHIR R4 Observation: code, value[x] (any of FHIR R4's eleven) or dataAbsentReason, and a combined device sample's vitals as component[] (each code, value[x], optional dataAbsentReason). The clinical time is effectiveDateTime, effectiveInstant or effectivePeriod.start, else issued, else the server's receipt; device is {reference, display}; the first identifier's value is stored as v1's refId. Other FHIR elements (meta, extension, performer, interpretation, referenceRange, …) are accepted and ignored. v1's observedAt (it wins over effective[x]), refId, string dataAbsentReason and device.id still work. A node with dataAbsentReason and no value is judged as carrying no value, and the rules read the reason as absent. valueSampledData is judged by its latest sample and stored whole, and the rules read every sample as samples. A valueDateTime, on the reading or a component, is judged and aggregated as epoch ms (valueNumber) and listed as sent. A valueBoolean is judged as 1 or 0. A valueTime is judged as ms since midnight, a valuePeriod as its length in ms (none while open or without an offset), a valueRatio as its quotient, and each is also kept as text (valueString); a valueRange is judged as the text low..high.
History is never judged. A reading whose category has a coding the tenant names as history (its historyCategories; the default pack's: batch-data, statistics, presence-batch, derived) is stored and deduplicated like any other, answered with no alerts, and never judged nor read by the rules.
The caller must be one of the patient's submitters, admins included: a known patient it is not attached to is a 403, an unknown one a 404 with type PATIENT_NOT_FOUND.
Idempotent. A reading is named by its first identifier (system|value), else by its clinical time, code, device and refId. A resend of one stored within the last hour is a 409 DUPLICATE_READING whose data.observationId is the stored reading, and is neither stored nor evaluated again. A reading with neither an identifier nor a clinical time is not deduplicated.
Concurrent requests are batched server-side. With Prefer: respond-sync evaluation finishes first and the reply adds alertIds, alerts ([{id, code}]), resolvedAlertIds and ruleCoverage; without it mode is async and alerts are delivered by webhook.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
Prefer | header | no | respond-sync evaluates the readings before answering: the response reports the alerts they raised and closed, and no webhook is sent for them. Without it the readings are stored and evaluated the same way before the response, which carries no alerts: they are delivered by webhook. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
patientRefId | string | no | |
resourceType | string | no | |
identifier | V1IdentifierDto[] | no | |
refId | string | no | |
status | string | no | |
category | object[] | no | Its codings' codes are stored; a code the tenant names in historyCategories makes the reading history: stored, never judged. |
note | object | no | Accepted as a plain string or as FHIR's [{text, time}] Annotations, which the mapper flattens to newline-joined text. Deliberately untyped: typing it as a string would reject real readings ovok sends today. |
code | V1ReadingCodeDto | yes | |
subject | V1ReferenceDto | no | |
component | V1ComponentDto[] | no | |
device | object | no | id (v1) or reference (FHIR) names the device. |
dataAbsentReason | object | no | v1's string or FHIR's CodeableConcept; untyped so that neither is refused. |
observedAt | string | no | |
effectiveDateTime | string | no | |
effectiveInstant | string | no | |
effectivePeriod | object | no | Only .start and .end are read, as in v1. |
issued | string | no | |
valueQuantity | V1QuantityDto | no | |
valueSampledData | V1SampledDataDto | no | |
valueString | string | no | |
valueInteger | number | no | |
valueBoolean | boolean | no | |
valueDateTime | string | no | |
valueTime | string | no | |
valuePeriod | object | no | |
valueRange | V1RangeDto | no | |
valueRatio | V1RatioDto | no | |
valueCodeableConcept | V1CodeableConceptDto | no |
Responses
| Status | Meaning |
|---|---|
200 | The reading as stored, plus the ingest outcome. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No patient with that refId in this tenant. |
409 | A resend of a reading already stored (DUPLICATE_READING, data.observationId); nothing was stored or evaluated. |
422 | The payload failed validation, or named no patient. |
503 | The evaluation backlog is full, or the readings could not be stored and judged (no database connection free in time, a lock timeout, a stalled database). Nothing was stored; resend after Retry-After (2 s). |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | yes | The same value as id. |
id | string | yes | |
patient | string | yes | The Signals patient id. |
code | object | yes | As sent: a FHIR CodeableConcept. Example: {"coding":[{"system":"http://loinc.org","code":"8867-4"}]}. |
valueQuantity | object | no | Example: {"value":72,"unit":"/min"}. |
observedAt | date-time | no | Example: "2026-08-27T09:15:00.000Z". |
createdAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
updatedAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
observationIds | string[] | yes | |
mode | string | yes | Evaluation finishes before this response in both modes. sync (only under Prefer: respond-sync) means its alerts are reported here rather than by webhook; async means no alerts are reported here and they are delivered by webhook. One of: sync, async. |
alertIds | string[] | no | |
alerts | RaisedAlertSchema[] | no | Sync mode only: alertIds with each alert's code, in the same order. |
resolvedAlertIds | string[] | no | Sync mode only: the alerts this call closed, which no webhook reports either. |
evaluated | number | no | |
ruleCoverage | RuleCoverageSchema | no |
POST /api/observation/{patientId}/batch
/api/observation/{patientId}/batchSubmit several readings for one patient
{observations: [<FHIR Observation>]}, each as POST /api/observation/:patientId takes it. In one transaction, evaluated in the order given. Answers v1's array, one entry per reading in request order: the reading as stored, or for a resend the 409 DUPLICATE_READING error body in its place. An array has nowhere to carry the ingest outcome, so a caller that needs alertIds posts them singly.
The body is a FHIR R4 Observation: code, value[x] (any of FHIR R4's eleven) or dataAbsentReason, and a combined device sample's vitals as component[] (each code, value[x], optional dataAbsentReason). The clinical time is effectiveDateTime, effectiveInstant or effectivePeriod.start, else issued, else the server's receipt; device is {reference, display}; the first identifier's value is stored as v1's refId. Other FHIR elements (meta, extension, performer, interpretation, referenceRange, …) are accepted and ignored. v1's observedAt (it wins over effective[x]), refId, string dataAbsentReason and device.id still work. A node with dataAbsentReason and no value is judged as carrying no value, and the rules read the reason as absent. valueSampledData is judged by its latest sample and stored whole, and the rules read every sample as samples. A valueDateTime, on the reading or a component, is judged and aggregated as epoch ms (valueNumber) and listed as sent. A valueBoolean is judged as 1 or 0. A valueTime is judged as ms since midnight, a valuePeriod as its length in ms (none while open or without an offset), a valueRatio as its quotient, and each is also kept as text (valueString); a valueRange is judged as the text low..high.
History is never judged. A reading whose category has a coding the tenant names as history (its historyCategories; the default pack's: batch-data, statistics, presence-batch, derived) is stored and deduplicated like any other, answered with no alerts, and never judged nor read by the rules.
The caller must be one of the patient's submitters, admins included: a known patient it is not attached to is a 403, an unknown one a 404 with type PATIENT_NOT_FOUND.
Idempotent. A reading is named by its first identifier (system|value), else by its clinical time, code, device and refId. A resend of one stored within the last hour is a 409 DUPLICATE_READING whose data.observationId is the stored reading, and is neither stored nor evaluated again. A reading with neither an identifier nor a clinical time is not deduplicated.
Concurrent requests are batched server-side. With Prefer: respond-sync evaluation finishes first and the reply adds alertIds, alerts ([{id, code}]), resolvedAlertIds and ruleCoverage; without it mode is async and alerts are delivered by webhook.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
patientId | path | yes | The Signals patient id. |
Prefer | header | no | respond-sync evaluates the readings before answering: the response reports the alerts they raised and closed, and no webhook is sent for them. Without it the readings are stored and evaluated the same way before the response, which carries no alerts: they are delivered by webhook. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
observations | V1ObservationDto[] | yes |
Responses
| Status | Meaning |
|---|---|
200 | Per reading, in request order: the reading as stored, or a resend's 409 body. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such patient in this tenant. |
422 | The payload failed validation. |
503 | The evaluation backlog is full, or the readings could not be stored and judged (no database connection free in time, a lock timeout, a stalled database). Nothing was stored; resend after Retry-After (2 s). |
Response body
Array with no documented fields.
POST /api/observation/{patientId}
/api/observation/{patientId}Submit a reading for a patient id
subject is ignored: the path names the patient.
The body is a FHIR R4 Observation: code, value[x] (any of FHIR R4's eleven) or dataAbsentReason, and a combined device sample's vitals as component[] (each code, value[x], optional dataAbsentReason). The clinical time is effectiveDateTime, effectiveInstant or effectivePeriod.start, else issued, else the server's receipt; device is {reference, display}; the first identifier's value is stored as v1's refId. Other FHIR elements (meta, extension, performer, interpretation, referenceRange, …) are accepted and ignored. v1's observedAt (it wins over effective[x]), refId, string dataAbsentReason and device.id still work. A node with dataAbsentReason and no value is judged as carrying no value, and the rules read the reason as absent. valueSampledData is judged by its latest sample and stored whole, and the rules read every sample as samples. A valueDateTime, on the reading or a component, is judged and aggregated as epoch ms (valueNumber) and listed as sent. A valueBoolean is judged as 1 or 0. A valueTime is judged as ms since midnight, a valuePeriod as its length in ms (none while open or without an offset), a valueRatio as its quotient, and each is also kept as text (valueString); a valueRange is judged as the text low..high.
History is never judged. A reading whose category has a coding the tenant names as history (its historyCategories; the default pack's: batch-data, statistics, presence-batch, derived) is stored and deduplicated like any other, answered with no alerts, and never judged nor read by the rules.
The caller must be one of the patient's submitters, admins included: a known patient it is not attached to is a 403, an unknown one a 404 with type PATIENT_NOT_FOUND.
Idempotent. A reading is named by its first identifier (system|value), else by its clinical time, code, device and refId. A resend of one stored within the last hour is a 409 DUPLICATE_READING whose data.observationId is the stored reading, and is neither stored nor evaluated again. A reading with neither an identifier nor a clinical time is not deduplicated.
Concurrent requests are batched server-side. With Prefer: respond-sync evaluation finishes first and the reply adds alertIds, alerts ([{id, code}]), resolvedAlertIds and ruleCoverage; without it mode is async and alerts are delivered by webhook.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
patientId | path | yes | The Signals patient id. |
Prefer | header | no | respond-sync evaluates the readings before answering: the response reports the alerts they raised and closed, and no webhook is sent for them. Without it the readings are stored and evaluated the same way before the response, which carries no alerts: they are delivered by webhook. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resourceType | string | no | |
identifier | V1IdentifierDto[] | no | |
refId | string | no | |
status | string | no | |
category | object[] | no | Its codings' codes are stored; a code the tenant names in historyCategories makes the reading history: stored, never judged. |
note | object | no | Accepted as a plain string or as FHIR's [{text, time}] Annotations, which the mapper flattens to newline-joined text. Deliberately untyped: typing it as a string would reject real readings ovok sends today. |
code | V1ReadingCodeDto | yes | |
subject | V1ReferenceDto | no | |
component | V1ComponentDto[] | no | |
device | object | no | id (v1) or reference (FHIR) names the device. |
dataAbsentReason | object | no | v1's string or FHIR's CodeableConcept; untyped so that neither is refused. |
observedAt | string | no | |
effectiveDateTime | string | no | |
effectiveInstant | string | no | |
effectivePeriod | object | no | Only .start and .end are read, as in v1. |
issued | string | no | |
valueQuantity | V1QuantityDto | no | |
valueSampledData | V1SampledDataDto | no | |
valueString | string | no | |
valueInteger | number | no | |
valueBoolean | boolean | no | |
valueDateTime | string | no | |
valueTime | string | no | |
valuePeriod | object | no | |
valueRange | V1RangeDto | no | |
valueRatio | V1RatioDto | no | |
valueCodeableConcept | V1CodeableConceptDto | no |
Responses
| Status | Meaning |
|---|---|
200 | The reading as stored, plus the ingest outcome. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such patient in this tenant. |
409 | A resend of a reading already stored (DUPLICATE_READING, data.observationId); nothing was stored or evaluated. |
422 | The payload failed validation. |
503 | The evaluation backlog is full, or the readings could not be stored and judged (no database connection free in time, a lock timeout, a stalled database). Nothing was stored; resend after Retry-After (2 s). |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
_id | string | yes | The same value as id. |
id | string | yes | |
patient | string | yes | The Signals patient id. |
code | object | yes | As sent: a FHIR CodeableConcept. Example: {"coding":[{"system":"http://loinc.org","code":"8867-4"}]}. |
valueQuantity | object | no | Example: {"value":72,"unit":"/min"}. |
observedAt | date-time | no | Example: "2026-08-27T09:15:00.000Z". |
createdAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
updatedAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
observationIds | string[] | yes | |
mode | string | yes | Evaluation finishes before this response in both modes. sync (only under Prefer: respond-sync) means its alerts are reported here rather than by webhook; async means no alerts are reported here and they are delivered by webhook. One of: sync, async. |
alertIds | string[] | no | |
alerts | RaisedAlertSchema[] | no | Sync mode only: alertIds with each alert's code, in the same order. |
resolvedAlertIds | string[] | no | Sync mode only: the alerts this call closed, which no webhook reports either. |
evaluated | number | no | |
ruleCoverage | RuleCoverageSchema | no |
GET /api/observation/{patientId}
/api/observation/{patientId}List a patient's readings
Newest first by clinical time, in v1's envelope {items, total, page, pageSize, totalPages} with nest's nextCursor. from, to and code (comma-separated) filter as in v1; category (comma-separated) keeps the readings carrying any of those FHIR category codes. With from, a reading whose clinical time is more than an hour ahead of when it was stored is not found: the read skips the storage older than that, so it never waits on it. pageSize defaults to 10; above 200 it needs both from and to, and then reaches 10000. A page may start at most 10000 rows in; walk further with cursor.
Each item is a flat timeline entry (code, valueNumber, observedAt, category, valueSampledData, components, effectiveStart, effectiveEnd, deviceId, …) with v1's _id, id, patient, valueQuantity and createdAt beside it. fields=code,valueNumber returns exactly those keys instead.
Archived readings. Readings stored more than 28 days ago move to the archive. A window with from that reaches them reads them back: they are filtered, ordered, counted in total and paged with cursor or page exactly as the readings still in the database, merged with them. Without from, the list holds the readings still in the database.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
patientId | path | yes | The Signals patient id. |
page | query | no | 1-based, as v1 paged. A page may start at most 10000 rows in; walk further with cursor. |
pageSize | query | no | v1's page size; defaults to 10. Wins over limit when both are sent. |
from | query | no | Inclusive lower bound on clinical time; a reading timed over an hour after it was stored is missed. |
to | query | no | Inclusive upper bound on the reading's clinical time. |
code | query | no | One LOINC code, or several separated by commas. |
category | query | no | One FHIR category code, or several separated by commas; a reading carrying any of them. |
limit | query | no | |
cursor | query | no | |
fields | query | no | Only these keys of each item, separated by commas (code,valueNumber,observedAt). Every key when absent. A chart reading a day of readings needs a few of them. |
Responses
| Status | Meaning |
|---|---|
200 | One page of readings. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such patient in this tenant. |
422 | A query parameter failed validation, a large page lacked from/to, or the page starts too deep. |
501 | The window reaches readings archived whole per chunk, before archives were kept per patient (ARCHIVE_LAYOUT_UNREADABLE). A window from data.readableFrom plus an hour on is readable. |
503 | The window reaches archived readings and the archive could not be reached (ARCHIVE_UNAVAILABLE). No partial page is answered; resend after Retry-After (5 s). |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
items | V1ObservationEntrySchema[] | yes | Exactly the fields keys instead, when fields is sent. |
total | number | yes | |
page | number | yes | 1-based. |
pageSize | number | yes | |
totalPages | number | yes | |
nextCursor | string | null | yes | Opaque keyset cursor. |
Updated 11 days ago