# Replace an org's rule settings

Canonical page: https://docs.ovok.com/signals/standalone/api/settings/replace-an-orgs-rule-settings

{/* Generated from the API Explorer document by scripts/generate-signals-api-pages.mjs. Edit ovok-core, not this page. */}


# Replace an org's rule settings [#replace-an-orgs-rule-settings]

| Method | Path |
| --- | --- |
| `PUT` | `/v1/signals/api/settings/org` |

<Availability route="PUT /v1/signals/api/settings/org" />

<Callout type="warn" title="Deprecated">


This route is deprecated. The description below names its successor.


</Callout>

Deprecated: a tenant's rule settings are `orgSettings` on `GET` and `PATCH /api/tenant`. This route still serves the per-project rows of a tenant several projects share.

Replaces the settings for `project`, or the tenant-wide row without it, whole. A patient whose `metadata.project` has a row reads that row; any other patient reads the tenant-wide row. The two are not merged. A tenant-wide write first makes a tenant's only project row its tenant-wide row, as `PATCH /api/tenant` does. Audited as `UPDATE_ORG_SETTINGS`.

With `ifAbsent=true` the row is created only when none exists and never replaced, so a default seeded at enrolment cannot overwrite a concurrent save; the answer adds `created` and carries the stored document either way, and only a creation is audited.

A body whose `settings` has no `triggers` key keeps the stored `triggers` (the home defaults seeded by Signals, or triggers pushed through the config routes); a body that sends `triggers`, `{}` included, replaces them.

The body may carry `resolvedAt` (ISO 8601), when the caller resolved this write: it lands only over a stored write resolved earlier, or stored without one, and is otherwise refused 409 `STALE_SETTINGS` with nothing written or audited. A write without `resolvedAt` always lands and keeps the stored stamp.

Signals stores `settings` as given and reads it only through the triggers it holds (`triggers`, the home's and the resident's own): what each other key means is theirs, so the object is checked for shape and size only. The default pack reads `bands` — per code `{ low?, high? }`, `{ mode: 'baseline', pct, low?, high? }` (outside either band fires; a patient's own baseline band with no sides of its own is judged alone) or `"NO_THRESHOLD"` — and `outOfBed`: `{ limitSeconds, enabled?, returnSeconds?, window?: { start: 'HH:MM', end: 'HH:MM', timeZone } }`. A patient's own key wins over the org's; extra keys are ignored. See tech/RULES-ENGINE.md.

### Through ovok [#through-ovok]

- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_config:update`, `signals_silence:update`. Project admins have every capability; client applications get no admin bypass.
- Your tenant keeps one org row, the tenant-wide one, so `project` isn't taken.
- It can reach any patient of your project without naming one, so it is for callers that reach every patient: project admins, manager or submitter apps, and anyone whose Patient access has no criteria.
- Deprecated. Use `/v1/signals/api/tenant`.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ifAbsent` | boolean | No | Create the row only when none exists, never replace one: a default seeded at enrolment must not overwrite a concurrent save of the home. |

### Body [#body]

Required. Schema `WriteStampedSettingsDto`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resolvedAt` | string | No | — |
| `settings` | object | Yes | — |

## Responses [#responses]

| Status | Meaning |
| --- | --- |
| `200` | The settings as stored, kept `triggers` included (with `created` under `ifAbsent`). |
| `400` | The query carries a raw `#`, or more than 200 parameters. |
| `401` | Your ovok access token, or your client id and secret, are missing or invalid. |
| `403` | ovok refused the call: you lack a capability this route needs, or your session has no project, or your access covers only some patients. From Signals: Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
| `409` | Your project has no Signals tenant of its own (`SIGNALS_TENANT_NOT_OWN`), or it is moving to another one. From Signals: A write resolved no later than the stored one (`STALE_SETTINGS`); nothing was written. |
| `415` | The body is not JSON. |
| `422` | `project` was sent, or `resolvedAt` is more than 5 minutes ahead of now. From Signals: `settings` is missing, is not a plain object or is over 64 KiB, or `project` or `resolvedAt` is invalid. |
| `429` | Too many requests. Retry after the seconds in `Retry-After`. |
| `500` | ovok hit an unexpected fault, such as your project having no Signals submitter. |
| `502` | Signals answered with something ovok couldn't use, or refused ovok's own credential. |
| `503` | Signals is unavailable. Retry after the seconds in `Retry-After`. |
| `504` | Signals did not answer in time. |

## Example [#example]

```bash
curl --request PUT 'https://api.sandbox.ovok.com/v1/signals/api/settings/org' \
  --user "${OVOK_CLIENT_ID}:${OVOK_CLIENT_SECRET}" \
  --header 'Content-Type: application/json' \
  --data @body.json
```