Thresholds

Update threshold

Update threshold using Ovok’s Slim API.

MethodPath
PUT/v1/slim/threshold

Authentication · Access policies

Replaces the home's threshold configuration: the alert limits every resident follows unless they have limits of their own.

Deprecated. Use PUT /v2/slim/threshold. This v1 route stays available until every client has moved.

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 PlanDefinition:update (admins and super admins skip this check). Scope: The caller's project (from the token).

Request

Body

Keys not listed below are ignored. A metric you leave out is stored with its default: disabled, with zero bounds. Every metric object takes only the organization mode: this route sets the home's limits, never a resident's.

NameTypeRequiredDescription
status"active" | "retired"YesSend active. retired stores the home's template as retired, and reads then answer the empty template.
idstringNoIgnored. The home's template is found by the caller's project.
projectIdstringNoIgnored. The caller's project is used.
datestring (ISO 8601 date-time)NoIgnored. The save time is used.
settingsobjectYesThe home's limits per metric.
settings.heartRateobjectNoHeart-rate limit. Default: disabled, absolute of 0 to 0.
settings.heartRate.mode"organization"NoDefault "organization". Any other value answers 422.
settings.heartRate.enabledbooleanYes, if the object is sentWhether the metric alerts. false also switches both bands off (see Behaviour).
settings.heartRate.absoluteobjectYes, if the object is sentThe fixed band.
settings.heartRate.absolute.enabledbooleanYesWhether the fixed band is armed.
settings.heartRate.absolute.minnumberYesLower bound in beats per minute. At least 0. Must not exceed max.
settings.heartRate.absolute.maxnumberYesUpper bound in beats per minute. At most 1000.
settings.respiratoryRateobjectNoRespiratory-rate limit. Same fields as settings.heartRate, in breaths per minute.
settings.meanHeartRateobjectNoBaseline (mean) heart-rate band. Default: disabled.
settings.meanHeartRate.mode"organization"NoDefault "organization".
settings.meanHeartRate.enabledbooleanYes, if the object is sentWhether the metric alerts.
settings.meanHeartRate.relativeobjectYes, if the object is sentThe band as multipliers of the resident's baseline.
settings.meanHeartRate.relative.enabledbooleanYesMust be false (or the metric enabled: false): a home-wide baseline band answers 422.
settings.meanHeartRate.relative.minnumberYesLower multiplier. At least 0. Must not exceed max.
settings.meanHeartRate.relative.maxnumberYesUpper multiplier. At most 1000.
settings.meanRespiratoryRateobjectNoBaseline (mean) respiratory-rate band. Same fields as settings.meanHeartRate.
settings.durationOfOutOfBedobjectNoOut-of-bed limit. Default: disabled, absolute of 0 seconds, window 19:00:00 to 09:00:00.
settings.durationOfOutOfBed.mode"organization"NoDefault "organization".
settings.durationOfOutOfBed.enabledbooleanYes, if the object is sentWhether the metric alerts.
settings.durationOfOutOfBed.periodobjectNoThe bed-time window. Default { "start": "19:00:00", "end": "09:00:00" }.
settings.durationOfOutOfBed.period.startstring (HH:MM:SS)Yes, if period is sentWindow start.
settings.durationOfOutOfBed.period.endstring (HH:MM:SS) | nullNoWindow end. Equal to start means 24 hours; before start crosses midnight. Send it: a window with neither end nor durationSeconds is not stored.
settings.durationOfOutOfBed.period.timezonestring | nullNoTime zone stored with the window.
settings.durationOfOutOfBed.period.durationSecondsnumberNoDeprecated. 0 to 86400. Used only to derive end when end is left out.
settings.durationOfOutOfBed.period.mode"organization" | "patient"NoAccepted and ignored.
settings.durationOfOutOfBed.absoluteobjectNoThe longest exit allowed.
settings.durationOfOutOfBed.absolute.enabledbooleanYes, if the object is sentWhether the limit is armed.
settings.durationOfOutOfBed.absolute.maxnumberYes, if the object is sentSeconds, at most 1000000. Rounded down to a multiple of 60.
settings.durationOfOutOfBed.relativeobjectNoA relative band. enabled (boolean) and max (number, at most 100) only; a min is dropped.
settings.sleepDurationobjectNoSleep-duration limit. Default: disabled, 0 to 0.
settings.sleepDuration.mode"organization"NoDefault "organization".
settings.sleepDuration.enabledbooleanYes, if the object is sentWhether the metric alerts.
settings.sleepDuration.absoluteobjectYes, if the object is sent{ enabled, min, max } in hours. min at least 0, max at most 1000, min not above max.
settings.numberOfTimesGettingOutOfBedobjectNoOut-of-bed count limit. Default: disabled, max 0.
settings.numberOfTimesGettingOutOfBed.mode"organization"NoDefault "organization".
settings.numberOfTimesGettingOutOfBed.enabledbooleanYes, if the object is sentWhether the metric alerts.
settings.numberOfTimesGettingOutOfBed.absoluteobjectYes, if the object is sent{ enabled, max }. max at most 1000.

Behaviour

  • The body replaces the stored settings; fields you omit take their schema defaults. The home's limit ranges and optional vitals, which v1 cannot send, are kept as stored.
  • The out-of-bed relative band, which v2 sets with deviationPercent, cannot survive a v1 save: v1 drops its min, so the band is cleared. The bed-time window is replaced too: leaving period out stores the default 19:00 to 09:00. Use PUT /v2/slim/threshold to keep either.
  • Units: durationOfOutOfBed is in seconds, sleepDuration in hours.
  • enabled: false switches a metric fully off: its absolute and relative bands are stored off too, whatever their own enabled says, and the residents following the home hold no Signals limit for it (a resident with limits of their own keeps them). Out of bed keeps its relative band, which only tightens its limit while it is on.
  • To switch a metric back on, send its band's enabled: true as well. A switch-off stores the band's flag false, so a body that sets only the metric's enabled: true reads back enabled: true but arms nothing: the residents following the home get no limit for it.
  • meanHeartRate and meanRespiratoryRate relative bands cannot be enabled for the home: a resident without a baseline of their own would get no alarm from them. Set baseline limits per resident with PUT /v2/slim/threshold/patient/{patientId}. One sent under enabled: false is stored off.
  • Every save writes the home's settings to Signals before it answers, even when nothing changed. Residents following the home use the saved settings at once; residents with their own limits keep them. The save succeeds only after Signals confirms the settings.
  • If the save leaves out-of-bed alerting off, Ovok first writes each resident's own out-of-bed limit to Signals. If Signals refuses any of those writes, the request answers 502 and the home document is not saved.
  • If Signals does not accept the settings, Ovok restores the previous state and returns saved: false: 409 when another home save or tenant move conflicts, 502 when Signals refuses the write or it runs out of time, and 500 when restoring the previous limits fails. Nothing is saved; send the save again.
  • Changed metrics appear as Threshold rows in change history; an unchanged save writes no row. A home-wide save can write one row per current resident. See the key catalogue.
  • The response is the saved configuration, in the shape of Get current threshold.

Example

curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/threshold' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "active",
    "settings": {
      "heartRate": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "min": 40, "max": 120 } }
    }
  }'

Successful response

200 — Threshold updated successfully. The body is the configuration as saved. This example is for the request above: the metrics the body left out are stored disabled.

{
  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b31",
  "projectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b11",
  "status": "active",
  "date": "2026-10-09T09:12:44.000Z",
  "settings": {
    "heartRate": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "min": 40, "max": 120 } },
    "meanHeartRate": { "mode": "organization", "enabled": false, "relative": { "enabled": false, "min": 0, "max": 0 } },
    "respiratoryRate": { "mode": "organization", "enabled": false, "absolute": { "enabled": false, "min": 0, "max": 0 } },
    "meanRespiratoryRate": { "mode": "organization", "enabled": false, "relative": { "enabled": false, "min": 0, "max": 0 } },
    "durationOfOutOfBed": {
      "mode": "organization",
      "enabled": false,
      "period": { "mode": "organization", "start": "19:00:00", "end": "09:00:00", "timezone": null },
      "absolute": { "enabled": false, "max": 0 }
    },
    "sleepDuration": { "mode": "organization", "enabled": false, "absolute": { "enabled": false, "min": 0, "max": 0 } },
    "numberOfTimesGettingOutOfBed": { "mode": "organization", "enabled": false, "absolute": { "enabled": false, "max": 0 } }
  }
}
FieldTypeDescription
idstringThe id of the stored threshold document.
projectIdstringThe caller's project.
status"active" | "retired"The status that was saved.
datestring (ISO 8601 date-time)When this save was stored.
settingsobjectThe home's limits per metric, as stored.
settings.heartRateobjectHeart-rate limit.
settings.heartRate.mode"organization"Always organization.
settings.heartRate.enabledbooleanWhether the metric alerts.
settings.heartRate.absoluteobjectThe fixed band.
settings.heartRate.absolute.enabledbooleanWhether the fixed band is armed.
settings.heartRate.absolute.minnumberLower bound in beats per minute.
settings.heartRate.absolute.maxnumberUpper bound in beats per minute.
settings.respiratoryRateobjectRespiratory-rate limit. Same fields as settings.heartRate, in breaths per minute.
settings.meanHeartRateobjectBaseline (mean) heart-rate band.
settings.meanHeartRate.mode"organization"Always organization.
settings.meanHeartRate.enabledbooleanWhether the metric alerts.
settings.meanHeartRate.relativeobjectThe band as multipliers of the resident's baseline.
settings.meanHeartRate.relative.enabledbooleanWhether the relative band is armed. Always false after a save here.
settings.meanHeartRate.relative.minnumberLower multiplier.
settings.meanHeartRate.relative.maxnumberUpper multiplier.
settings.meanRespiratoryRateobjectBaseline (mean) respiratory-rate band. Same fields as settings.meanHeartRate.
settings.durationOfOutOfBedobjectOut-of-bed limit.
settings.durationOfOutOfBed.mode"organization"Always organization.
settings.durationOfOutOfBed.enabledbooleanWhether the metric alerts.
settings.durationOfOutOfBed.periodobjectThe window in which out-of-bed is checked. Omitted when the body stored none.
settings.durationOfOutOfBed.period.mode"organization"Always organization.
settings.durationOfOutOfBed.period.startstring (HH:MM:SS)Window start.
settings.durationOfOutOfBed.period.endstring (HH:MM:SS) | nullWindow end.
settings.durationOfOutOfBed.period.timezonestring | nullTime zone stored with the window, or null.
settings.durationOfOutOfBed.absoluteobjectThe longest exit allowed.
settings.durationOfOutOfBed.absolute.enabledbooleanWhether the limit is armed.
settings.durationOfOutOfBed.absolute.maxnumberThe longest exit allowed, in seconds, a multiple of 60.
settings.durationOfOutOfBed.relativeobjectOnly when the body stored one: { enabled, max }, with min omitted.
settings.sleepDurationobjectSleep-duration limit: mode, enabled and absolute ({ enabled, min, max } in hours).
settings.numberOfTimesGettingOutOfBedobjectOut-of-bed count limit: mode, enabled and absolute ({ enabled, max }).
settings.oxygenSaturationobjectOptional vital, present only when the home watches it (kept as stored; v1 cannot set it): { mode, enabled, absolute }.
settings.pulseRateobjectOptional vital. Same fields as settings.oxygenSaturation.
settings.perfusionIndexobjectOptional vital. Same fields as settings.oxygenSaturation.
settings.bodyTemperatureobjectOptional vital. Same fields as settings.oxygenSaturation.

Errors

StatusMeaning
400Your session has no project, or the FHIR server refused the write.
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, or you lack PlanDefinition:update.
409Another home save is running, the home is moving to another Signals tenant, or its settings changed while this save ran. The body has saved: false; nothing was saved. Send the save again.
422The body fails validation (including a mode other than organization) or enables a relative band on meanHeartRate or meanRespiratoryRate (home-wide bands are absolute only).
500The save failed and restoring the previous limits failed too. The body has saved: false.
502The home's stored thresholds could not be read, Signals refused the settings, or Signals did not confirm a resident's own out-of-bed limit before the home document was saved. The body has saved: false; nothing was saved. Send the save again.
503The access policy could not be read right now. Retry.

Last updated on

On this page