Signals API

Vitals ingestion and alerting.

Version 1.1 · 42 operations

Generated from the OpenAPI document by npm run docs:openapi. Do not edit by hand —
change the decorators in src/ and regenerate, or the next run will overwrite you.

Vitals ingestion and alerting.

Authentication. Every route uses HTTP Basic with an API client's
clientId and secret. The tenant is resolved server-side from that
credential and is never accepted from the request.

Roles. SUBMITTER posts readings for patients it is attached to,
SUBSCRIBER reads the records of patients it is attached to, MANAGER
administers the tenant, and ADMIN bypasses role checks.

Paging. List routes answer v1's envelope and page by page and limit
(pageSize for readings), up to 10000 rows deep. Every list also carries an
opaque keyset cursor: pass the nextCursor you were given back as cursor
to walk any depth. Do not construct or parse one — the encoding is not part of
this contract. A null nextCursor is the last page.

Errors. Every failure answers application/problem+json (RFC 9457):
type is the problem's URI, https://docs.ovok.com/errors/ plus its
machine code in kebab case (…/validation-error, …/patient-not-found),
status the HTTP status, detail what went wrong, instance the route
that failed, traceId the trace to quote when reporting it, and errors
one {field, code, params} per invalid field (FIELD_REQUIRED,
FIELD_INVALID_TYPE, …). v1's name, message, code (the status)
and data are kept beside them. A body that is not JSON is a 415, one that
cannot be parsed a 400, one too large a 413, and one that parses but fails
validation a 422. A 401 names its Basic challenge in WWW-Authenticate,
a 405 its methods in Allow, and a 429 or 503 when to retry in
Retry-After. A 5xx never names its cause in detail.

Timestamps. Always ISO-8601 in UTC with a trailing Z, on the way in and
on the way out.

Sections

SectionOperationsWhat it covers
Observations4Submitting 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.
Alerts1Alerts raised by evaluation. An alert opens on a breach, deduplicates on its TRIGGER:<code> key while it stays open, and closes when a trigger resolves it.
Patients11Patients and their alerting flags. refId is the caller's own identifier.
Settings6What the triggers judge by, per org (tenant and project) and per patient: the triggers themselves, bands per code and the out-of-bed limit. Opaque to Signals beyond triggers: the triggers give the other keys their meaning.
Patient config3v1's config writes addressed by a list of patient ids. A trigger is stored as sent in the patient's settings, where it judges its code; one without logic is rejected and reported. Reads are POSTs here too — a thousand ids do not fit in a query string.
Tenants2Tenant-level feature switches.
Clients10API credentials and their webhook subscriptions.
Events4Every webhook event queued, with how its delivery went, and sending it again: the safety net after a receiver outage.
Health1Liveness plus the pipeline check that alarms when readings arrive and nothing alerts, or alerts queue and nothing is delivered.
Schemas—Every response body shape.

Did this page help you?