# Update patient threshold

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

| Method | Path |
| --- | --- |
| `PUT` | `/v1/slim/threshold/patient/:patientId` |

[Authentication](/authentication) · [Access policies](/access-policies)

Saves one resident's own thresholds.

> **Deprecated.** Use [`PUT /v2/slim/threshold/patient/{patientId}`](/slim-apis/threshold/update-patient-threshold-v2). This v1 route stays available, unchanged, 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 `Goal:update` (admins and super admins skip this check).
**Scope:** The resident must be in the caller's project (from the token) or one of its sub-projects.

## Request [#request]

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `patientId` | `string (uuid)` | Yes | The resident's Patient id. The path decides the resident. |

### Body [#body]

Keys not listed below are ignored. Every metric takes the same fields as `settings.heartRate` (`mode`, `enabled`, `period`, `average`, `averageRange`) plus its own band block. A metric you leave out takes its default (`mode: "organization"`, disabled, zero bounds), which switches it off for this resident when the home has it on; send every metric you want to keep following the home.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `patientId` | `string` | Yes | Required but ignored; the path decides the resident. |
| `status` | `"active"` \| `"revoked"` | Yes | Required; the saved threshold is always `active`. |
| `id` | `string` | No | Ignored. |
| `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 resident's limits per metric. |
| `settings.heartRate` | `object` | No | Heart-rate limit. Default: organization, disabled, `absolute` of 0 to 0. |
| `settings.heartRate.mode` | `"organization"` \| `"patient"` | Yes, if the object is sent | `patient` stores your `absolute` / `relative` limits as the resident's own. `organization` follows the home. `"patient-auto"` answers 422. |
| `settings.heartRate.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. |
| `settings.heartRate.absolute` | `object` | No | The fixed band. |
| `settings.heartRate.absolute.enabled` | `boolean` | Yes, if `absolute` is sent | Whether the fixed band is armed. |
| `settings.heartRate.absolute.min` | `number` | Yes, if `absolute` is sent | Lower bound in beats per minute. At least 0. Must not exceed `max`. |
| `settings.heartRate.absolute.max` | `number` | Yes, if `absolute` is sent | Upper bound in beats per minute. At most 1000. |
| `settings.heartRate.period` | `object` | No | Bed-time window. Default `{ "start": "19:00:00", "end": "09:00:00" }`. Only `durationOfOutOfBed` uses it. |
| `settings.heartRate.average` | `number` | No | Ignored. Set by the server. |
| `settings.heartRate.averageRange` | `object` | No | Ignored. Set by the server. |
| `settings.respiratoryRate` | `object` | No | Respiratory-rate limit. Same fields as `settings.heartRate`, in breaths per minute, except that `absolute` is required when the object is sent. |
| `settings.meanHeartRate` | `object` | No | Baseline (mean) heart-rate band. Default: organization, disabled. |
| `settings.meanHeartRate.mode` | `"organization"` \| `"patient"` | Yes, if the object is sent | As for `settings.heartRate.mode`. |
| `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 | Whether the relative band is armed. Arming one needs a baseline average on record (see 424). |
| `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: organization, disabled, `absolute` of 0 seconds. |
| `settings.durationOfOutOfBed.mode` | `"organization"` \| `"patient"` | Yes, if the object is sent | As for `settings.heartRate.mode`. |
| `settings.durationOfOutOfBed.enabled` | `boolean` | Yes, if the object is sent | Whether the metric alerts. |
| `settings.durationOfOutOfBed.absolute` | `object` | No | The longest exit allowed. |
| `settings.durationOfOutOfBed.absolute.enabled` | `boolean` | Yes, if `absolute` is sent | Whether the limit is armed. |
| `settings.durationOfOutOfBed.absolute.max` | `number` | Yes, if `absolute` 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). |
| `settings.durationOfOutOfBed.period` | `object` | No | Bed-time window. Default `{ "start": "19:00:00", "end": "09:00:00" }`. |
| `settings.durationOfOutOfBed.period.mode` | `"organization"` \| `"patient"` | No | `patient` stores `start` and `end` as the resident's own window. Anything else uses the home's window. |
| `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. A window of 23 hours 59 minutes or more counts as the whole day for out-of-bed baseline evaluation. |
| `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.sleepDuration` | `object` | No | Sleep-duration limit. Default: organization, disabled. |
| `settings.sleepDuration.mode` | `"organization"` \| `"patient"` | Yes, if the object is sent | As for `settings.heartRate.mode`. |
| `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: organization, disabled. |
| `settings.numberOfTimesGettingOutOfBed.mode` | `"organization"` \| `"patient"` | Yes, if the object is sent | As for `settings.heartRate.mode`. |
| `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]

- Each metric's `mode` decides what is stored:
  - `patient`: your `absolute` / `relative` limits.
  - `organization`: the home's limits. Sending `enabled: false` for a metric the home has enabled switches it to `patient` mode, disabled. Leaving the metric out does the same.
- For a `patient` metric, `enabled: false` also stores its `absolute` and `relative` bands off (out of bed keeps its `relative` band), and a metric sent `enabled: true` with every band disabled is stored disabled.
- `patient-auto` is no longer accepted: a body that uses it is refused with 422.
- `patientId` in the body is required but ignored; the path decides the resident.
- `average` and `averageRange` are set by the server; values you send are ignored.
- Enabling a relative heart-rate or respiratory-rate band for a resident with no baseline average answers 424, because the band would have nothing to be relative to.
- Every save writes the resident's settings to Signals before it answers. A successful response has `signalsSync: { "status": "ok" }` once Signals holds the settings. If Signals does not accept them, Ovok restores the previous state and returns `502` with `saved: false`; nothing is saved. Send the save again.
- A second save for the same resident while one is running answers `409` with `saved: false` and changes nothing. Send it again after the first save finishes.
- The v1 body cannot set the optional vitals (stored ones are kept) or a working relative out-of-bed band (v1 drops its `min`), so saving a `patient` out-of-bed limit here clears the resident's own band. [`PUT /v2/slim/threshold/patient/{patientId}`](/slim-apis/threshold/update-patient-threshold-v2) sets both.
- Each changed metric appears as a `Threshold` row in [change history](/slim-apis/audit/list-change-history); an unchanged save writes no row. See the [key catalogue](/slim-apis/audit/change-history-keys).
- The response is the saved threshold, as stored: unlike a read, it is not overlaid with what Signals holds.

## Example [#example]

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/threshold/patient/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
    "status": "active",
    "settings": {
      "heartRate": { "mode": "patient", "enabled": true, "absolute": { "enabled": true, "min": 45, "max": 110 } },
      "meanHeartRate": { "mode": "organization", "enabled": false, "relative": { "enabled": false, "min": 0, "max": 0 } },
      "respiratoryRate": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "min": 0, "max": 0 } },
      "meanRespiratoryRate": { "mode": "organization", "enabled": false, "relative": { "enabled": false, "min": 0, "max": 0 } },
      "durationOfOutOfBed": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "max": 0 } },
      "sleepDuration": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "min": 0, "max": 0 } },
      "numberOfTimesGettingOutOfBed": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "max": 0 } }
    }
  }'
```

Only `heartRate` is the resident's own here. Every other metric follows the home, so the home's values replace the placeholder numbers.

## Successful response [#successful-response]

`200` — Patient threshold updated successfully.

```json
{
  "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "projectId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b11",
  "status": "active",
  "date": "2026-10-09T09:20:05.000Z",
  "period": { "start": "2026-10-09T09:20:05.000Z" },
  "settings": {
    "heartRate": {
      "period": { "start": "19:00:00", "end": "09:00:00" },
      "mode": "patient",
      "enabled": true,
      "absolute": { "enabled": true, "min": 45, "max": 110 }
    },
    "meanHeartRate": {
      "period": { "start": "19:00:00", "end": "09:00:00" },
      "mode": "organization",
      "enabled": false,
      "relative": { "enabled": false, "min": 0, "max": 0 }
    },
    "respiratoryRate": {
      "period": { "start": "19:00:00", "end": "09:00:00" },
      "mode": "organization",
      "enabled": true,
      "absolute": { "enabled": true, "min": 8, "max": 25 }
    },
    "meanRespiratoryRate": {
      "period": { "start": "19:00:00", "end": "09:00:00" },
      "mode": "organization",
      "enabled": false,
      "relative": { "enabled": false, "min": 0, "max": 0 }
    },
    "durationOfOutOfBed": {
      "period": { "mode": "organization", "start": "19:00:00", "end": "09:00:00", "timezone": null },
      "mode": "organization",
      "enabled": true,
      "absolute": { "enabled": true, "max": 600 }
    },
    "sleepDuration": {
      "period": { "start": "19:00:00", "end": "09:00:00" },
      "mode": "organization",
      "enabled": true,
      "absolute": { "enabled": true, "min": 7, "max": 10 }
    },
    "numberOfTimesGettingOutOfBed": {
      "period": { "start": "19:00:00", "end": "09:00:00" },
      "mode": "organization",
      "enabled": true,
      "absolute": { "enabled": true, "max": 0 }
    }
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `patientId` | `string` | The id from the path. |
| `projectId` | `string` | The caller's project. |
| `status` | `"active"` | Always `active`. |
| `date` | `string (ISO 8601 date-time)` | When this save was stored. |
| `period` | `object` | The save's own timestamp. |
| `period.start` | `string (ISO 8601 date-time)` | The save time, the same as `date`. |
| `settings` | `object` | The resident's limits per metric, as stored by this save. Every metric the body carried (or defaulted) is present. |
| `settings.heartRate` | `object` | Heart-rate limit. |
| `settings.heartRate.mode` | `"organization"` \| `"patient"` | `patient` for the resident's own limit; `organization` for one that follows the home. |
| `settings.heartRate.enabled` | `boolean` | Whether the metric alerts. |
| `settings.heartRate.absolute` | `object` | The fixed band. For an `organization` metric, the home's 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.heartRate.relative` | `object` | The relative (baseline) band as multipliers: `{ enabled, min, max }`. Only on metrics that carry one. |
| `settings.heartRate.period` | `object` | The bed-time window: `start` and `end` (`string (HH:MM:SS)`), plus `mode` and `timezone` on `durationOfOutOfBed`. Present on every metric; used only by `durationOfOutOfBed`. |
| `settings.heartRate.average` | `number` | The baseline average an armed relative band is anchored to. Omitted otherwise. |
| `settings.heartRate.averageRange` | `object` | The multipliers applied to `average`: `{ min, max }`. Omitted without `average`. |
| `settings.respiratoryRate` | `object` | Respiratory-rate limit. Same fields as `settings.heartRate`. |
| `settings.meanHeartRate` | `object` | Baseline (mean) heart-rate band: the same fields, with `relative` instead of `absolute`. |
| `settings.meanRespiratoryRate` | `object` | Baseline (mean) respiratory-rate band. Same fields as `settings.meanHeartRate`. |
| `settings.durationOfOutOfBed` | `object` | Out-of-bed limit. The same fields, with `absolute.max` in seconds. `period.mode` says whether the window is the home's or the resident's own. |
| `settings.sleepDuration` | `object` | Sleep-duration limit. The same fields, with `absolute.min` and `absolute.max` in hours. |
| `settings.numberOfTimesGettingOutOfBed` | `object` | Out-of-bed count limit. The same fields, with `absolute.max` a count. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | Your session has no project. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, you lack `Goal:update`, or the patient is outside your project and its sub-projects or carries no project. |
| [`409`](/errors/conflict) | Another save for this resident is running. The body has `saved: false`; nothing was changed. Send the save again after the first finishes. |
| [`422`](/errors/validation-failed) | The body fails validation (including `"patient-auto"` as a mode). |
| [`424`](/errors/failed-dependency) | The body arms a baseline (relative) band for a metric with no stored average for this resident. The body names the metrics in `missing`. |
| [`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, or Signals did not accept the resident's settings. 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. |
