# Update threshold

Canonical page: https://docs.ovok.com/slim-apis/threshold/update-threshold

| Method | Path |
| --- | --- |
| `PUT` | `/v1/slim/threshold` |

[Authentication](/authentication) · [Access policies](/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`](/slim-apis/threshold/update-org-threshold-v2). 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 [#request]

### Body [#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.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"active"` \| `"retired"` | Yes | Send `active`. `retired` stores the home's template as retired, and reads then answer the empty template. |
| `id` | `string` | No | Ignored. The home's template is found by the caller's project. |
| `projectId` | `string` | No | Ignored. The caller's project is used. |
| `date` | `string (ISO 8601 date-time)` | No | Ignored. The save time is used. |
| `settings` | `object` | Yes | The home's limits per metric. |
| `settings.heartRate` | `object` | No | Heart-rate limit. Default: disabled, `absolute` of 0 to 0. |
| `settings.heartRate.mode` | `"organization"` | No | Default `"organization"`. Any other value answers 422. |
| `settings.heartRate.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. `false` also switches both bands off (see Behaviour). |
| `settings.heartRate.absolute` | `object` | Yes, if the object is sent | The fixed band. |
| `settings.heartRate.absolute.enabled` | `boolean` | Yes | Whether the fixed band is armed. |
| `settings.heartRate.absolute.min` | `number` | Yes | Lower bound in beats per minute. At least 0. Must not exceed `max`. |
| `settings.heartRate.absolute.max` | `number` | Yes | Upper bound in beats per minute. At most 1000. |
| `settings.respiratoryRate` | `object` | No | Respiratory-rate limit. Same fields as `settings.heartRate`, in breaths per minute. |
| `settings.meanHeartRate` | `object` | No | Baseline (mean) heart-rate band. Default: disabled. |
| `settings.meanHeartRate.mode` | `"organization"` | No | Default `"organization"`. |
| `settings.meanHeartRate.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. |
| `settings.meanHeartRate.relative` | `object` | Yes, if the object is sent | The band as multipliers of the resident's baseline. |
| `settings.meanHeartRate.relative.enabled` | `boolean` | Yes | Must be `false` (or the metric `enabled: false`): a home-wide baseline band answers 422. |
| `settings.meanHeartRate.relative.min` | `number` | Yes | Lower multiplier. At least 0. Must not exceed `max`. |
| `settings.meanHeartRate.relative.max` | `number` | Yes | Upper multiplier. At most 1000. |
| `settings.meanRespiratoryRate` | `object` | No | Baseline (mean) respiratory-rate band. Same fields as `settings.meanHeartRate`. |
| `settings.durationOfOutOfBed` | `object` | No | Out-of-bed limit. Default: disabled, `absolute` of 0 seconds, window 19:00:00 to 09:00:00. |
| `settings.durationOfOutOfBed.mode` | `"organization"` | No | Default `"organization"`. |
| `settings.durationOfOutOfBed.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. |
| `settings.durationOfOutOfBed.period` | `object` | No | The bed-time window. Default `{ "start": "19:00:00", "end": "09:00:00" }`. |
| `settings.durationOfOutOfBed.period.start` | `string (HH:MM:SS)` | Yes, if `period` is sent | Window start. |
| `settings.durationOfOutOfBed.period.end` | `string (HH:MM:SS) \| null` | No | Window 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.timezone` | `string \| null` | No | Time zone stored with the window. |
| `settings.durationOfOutOfBed.period.durationSeconds` | `number` | No | Deprecated. 0 to 86400. Used only to derive `end` when `end` is left out. |
| `settings.durationOfOutOfBed.period.mode` | `"organization"` \| `"patient"` | No | Accepted and ignored. |
| `settings.durationOfOutOfBed.absolute` | `object` | No | The longest exit allowed. |
| `settings.durationOfOutOfBed.absolute.enabled` | `boolean` | Yes, if the object is sent | Whether the limit is armed. |
| `settings.durationOfOutOfBed.absolute.max` | `number` | Yes, if the object is sent | Seconds, at most 1000000. Rounded down to a multiple of 60. |
| `settings.durationOfOutOfBed.relative` | `object` | No | A relative band. `enabled` (`boolean`) and `max` (`number`, at most 100) only; a `min` is dropped. |
| `settings.sleepDuration` | `object` | No | Sleep-duration limit. Default: disabled, 0 to 0. |
| `settings.sleepDuration.mode` | `"organization"` | No | Default `"organization"`. |
| `settings.sleepDuration.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. |
| `settings.sleepDuration.absolute` | `object` | Yes, if the object is sent | `{ enabled, min, max }` in hours. `min` at least 0, `max` at most 1000, `min` not above `max`. |
| `settings.numberOfTimesGettingOutOfBed` | `object` | No | Out-of-bed count limit. Default: disabled, `max` 0. |
| `settings.numberOfTimesGettingOutOfBed.mode` | `"organization"` | No | Default `"organization"`. |
| `settings.numberOfTimesGettingOutOfBed.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. |
| `settings.numberOfTimesGettingOutOfBed.absolute` | `object` | Yes, if the object is sent | `{ enabled, max }`. `max` at most 1000. |

## Behaviour [#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`](/slim-apis/threshold/update-org-threshold-v2) 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}`](/slim-apis/threshold/update-patient-threshold-v2). 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](/slim-apis/audit/list-change-history); an unchanged save writes no row. A home-wide save can write one row per current resident. See the [key catalogue](/slim-apis/audit/change-history-keys).
- The response is the saved configuration, in the shape of [Get current threshold](/slim-apis/threshold/get-current-threshold).

## Example [#example]

```bash
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 [#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.

```json
{
  "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 } }
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The id of the stored threshold document. |
| `projectId` | `string` | The caller's project. |
| `status` | `"active"` \| `"retired"` | The status that was saved. |
| `date` | `string (ISO 8601 date-time)` | When this save was stored. |
| `settings` | `object` | The home's limits per metric, as stored. |
| `settings.heartRate` | `object` | Heart-rate limit. |
| `settings.heartRate.mode` | `"organization"` | Always `organization`. |
| `settings.heartRate.enabled` | `boolean` | Whether the metric alerts. |
| `settings.heartRate.absolute` | `object` | The fixed band. |
| `settings.heartRate.absolute.enabled` | `boolean` | Whether the fixed band is armed. |
| `settings.heartRate.absolute.min` | `number` | Lower bound in beats per minute. |
| `settings.heartRate.absolute.max` | `number` | Upper bound in beats per minute. |
| `settings.respiratoryRate` | `object` | Respiratory-rate limit. Same fields as `settings.heartRate`, in breaths per minute. |
| `settings.meanHeartRate` | `object` | Baseline (mean) heart-rate band. |
| `settings.meanHeartRate.mode` | `"organization"` | Always `organization`. |
| `settings.meanHeartRate.enabled` | `boolean` | Whether the metric alerts. |
| `settings.meanHeartRate.relative` | `object` | The band as multipliers of the resident's baseline. |
| `settings.meanHeartRate.relative.enabled` | `boolean` | Whether the relative band is armed. Always `false` after a save here. |
| `settings.meanHeartRate.relative.min` | `number` | Lower multiplier. |
| `settings.meanHeartRate.relative.max` | `number` | Upper multiplier. |
| `settings.meanRespiratoryRate` | `object` | Baseline (mean) respiratory-rate band. Same fields as `settings.meanHeartRate`. |
| `settings.durationOfOutOfBed` | `object` | Out-of-bed limit. |
| `settings.durationOfOutOfBed.mode` | `"organization"` | Always `organization`. |
| `settings.durationOfOutOfBed.enabled` | `boolean` | Whether the metric alerts. |
| `settings.durationOfOutOfBed.period` | `object` | The window in which out-of-bed is checked. Omitted when the body stored none. |
| `settings.durationOfOutOfBed.period.mode` | `"organization"` | Always `organization`. |
| `settings.durationOfOutOfBed.period.start` | `string (HH:MM:SS)` | Window start. |
| `settings.durationOfOutOfBed.period.end` | `string (HH:MM:SS) \| null` | Window end. |
| `settings.durationOfOutOfBed.period.timezone` | `string \| null` | Time zone stored with the window, or `null`. |
| `settings.durationOfOutOfBed.absolute` | `object` | The longest exit allowed. |
| `settings.durationOfOutOfBed.absolute.enabled` | `boolean` | Whether the limit is armed. |
| `settings.durationOfOutOfBed.absolute.max` | `number` | The longest exit allowed, in seconds, a multiple of 60. |
| `settings.durationOfOutOfBed.relative` | `object` | Only when the body stored one: `{ enabled, max }`, with `min` omitted. |
| `settings.sleepDuration` | `object` | Sleep-duration limit: `mode`, `enabled` and `absolute` (`{ enabled, min, max }` in hours). |
| `settings.numberOfTimesGettingOutOfBed` | `object` | Out-of-bed count limit: `mode`, `enabled` and `absolute` (`{ enabled, max }`). |
| `settings.oxygenSaturation` | `object` | Optional vital, present only when the home watches it (kept as stored; v1 cannot set it): `{ mode, enabled, absolute }`. |
| `settings.pulseRate` | `object` | Optional vital. Same fields as `settings.oxygenSaturation`. |
| `settings.perfusionIndex` | `object` | Optional vital. Same fields as `settings.oxygenSaturation`. |
| `settings.bodyTemperature` | `object` | Optional vital. Same fields as `settings.oxygenSaturation`. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | Your session has no project, or the FHIR server refused the write. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, or you lack `PlanDefinition:update`. |
| [`409`](/errors/conflict) | Another 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. |
| [`422`](/errors/validation-failed) | The body fails validation (including a `mode` other than `organization`) or enables a relative band on `meanHeartRate` or `meanRespiratoryRate` (home-wide bands are absolute only). |
| [`500`](/errors/internal-error) | The save failed and restoring the previous limits failed too. The body has `saved: false`. |
| [`502`](/errors/upstream-error) | The 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. |
| [`503`](/errors/service-unavailable) | The access policy could not be read right now. Retry. |
