Settings
What 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.
| Operation | Endpoint |
|---|---|
| Get an org's rule settings | GET /api/settings/org |
| Replace an org's rule settings | PUT /api/settings/org |
| Get a patient's own rule settings | GET /api/patient/{id}/settings |
| Replace a patient's own rule settings | PUT /api/patient/{id}/settings |
| Merge keys into a patient's own rule settings | PATCH /api/patient/{id}/settings |
| List the tenant's patient rule settings by key | GET /api/patient-settings |
GET /api/settings/org (deprecated)
/api/settings/org (deprecated)Get an org's rule settings
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.
The settings for project, or the tenant-wide row without it. {} when none were written.
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?, 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.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
project | query | no | Absent: the tenant-wide row, which a patient with no project row reads. |
Responses
| Status | Meaning |
|---|---|
200 | The settings. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
422 | project is empty or longer than 200 characters. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
project | string | null | yes | The project these settings are for; null for the tenant-wide row. |
settings | object | yes | Opaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}. |
created | boolean | no | PUT ?ifAbsent=true only: whether this call created the row. |
PUT /api/settings/org (deprecated)
/api/settings/org (deprecated)Replace an org's rule settings
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.
For each patient the write reaches, judged by its own settings over the org's: a band changed ends the episode judged under the old one THRESHOLD_CHANGED; a code switched off (its band "NO_THRESHOLD", or out of bed enabled: false) has its active alert resolved and its open episode closed THRESHOLD_CHANGED at the save, the other codes' left alone; an acknowledged out-of-bed absence, whose episode the ack closed, has its still-active alert resolved; a band deleted closes nothing.
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?, 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.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
project | query | no | Absent: the tenant-wide row, which a patient with no project row reads. |
ifAbsent | query | 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. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resolvedAt | string | no | |
settings | object | yes |
Responses
| Status | Meaning |
|---|---|
200 | The settings as stored, kept triggers included (with created under ifAbsent). |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
409 | A write resolved no later than the stored one (STALE_SETTINGS); nothing was written. |
422 | settings is missing, is not a plain object or is over 64 KiB, or project or resolvedAt is invalid. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
project | string | null | yes | The project these settings are for; null for the tenant-wide row. |
settings | object | yes | Opaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}. |
created | boolean | no | PUT ?ifAbsent=true only: whether this call created the row. |
GET /api/patient/{id}/settings
/api/patient/{id}/settingsGet a patient's own rule settings
{} when none were written.
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?, 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.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The Signals patient id. |
Responses
| Status | Meaning |
|---|---|
200 | The settings. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such patient in this tenant. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
patientId | string | yes | |
settings | object | yes | Opaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}. |
PUT /api/patient/{id}/settings
/api/patient/{id}/settingsReplace a patient's own rule settings
Replaced whole. The triggers read them beside the org's, as settings.individual. Audited as UPDATE_PATIENT_SETTINGS.
For each patient the write reaches, judged by its own settings over the org's: a band changed ends the episode judged under the old one THRESHOLD_CHANGED; a code switched off (its band "NO_THRESHOLD", or out of bed enabled: false) has its active alert resolved and its open episode closed THRESHOLD_CHANGED at the save, the other codes' left alone; an acknowledged out-of-bed absence, whose episode the ack closed, has its still-active alert resolved; a band deleted closes nothing.
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?, 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.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The Signals patient id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resolvedAt | string | no | |
settings | object | yes |
Responses
| Status | Meaning |
|---|---|
200 | The settings as stored. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such patient in this tenant. |
409 | A write resolved no later than the stored one (STALE_SETTINGS); nothing was written. |
422 | settings is missing, is not a plain object or is over 64 KiB, or resolvedAt is invalid. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
patientId | string | yes | |
settings | object | yes | Opaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}. |
PATCH /api/patient/{id}/settings
/api/patient/{id}/settingsMerge keys into a patient's own rule settings
Merges the top-level keys of settings into the stored object in one statement: a key sent replaces the stored one, a key sent as null is removed, every other key is kept, and the row is created when the patient has none. Audited as UPDATE_PATIENT_SETTINGS, with the stored document before and after.
For each patient the write reaches, judged by its own settings over the org's: a band changed ends the episode judged under the old one THRESHOLD_CHANGED; a code switched off (its band "NO_THRESHOLD", or out of bed enabled: false) has its active alert resolved and its open episode closed THRESHOLD_CHANGED at the save, the other codes' left alone; an acknowledged out-of-bed absence, whose episode the ack closed, has its still-active alert resolved; a band deleted closes nothing.
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?, 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.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The Signals patient id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resolvedAt | string | no | |
settings | object | yes |
Responses
| Status | Meaning |
|---|---|
200 | The settings as stored after the merge. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such patient in this tenant. |
409 | A write resolved no later than the stored one (STALE_SETTINGS); nothing was written. |
422 | settings is missing, is not a plain object or is over 64 KiB (or would be once merged), or resolvedAt is invalid. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
patientId | string | yes | |
settings | object | yes | Opaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}. |
GET /api/patient-settings
/api/patient-settingsList the tenant's patient rule settings by key
The patients of the tenant that have a settings row, ascending by patientId, each with only the requested top-level keys it holds (a key it lacks is left out). refId is the patient's reference id, or null. nextCursor is null on the last page; pass it back as cursor for the next.
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?, 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.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
keys | query | yes | The top-level settings keys to return, comma-separated: residentLimits,bands. |
limit | query | no | Page size, 1 to 500. Defaults to 200. |
cursor | query | no | Opaque keyset cursor: a previous answer's nextCursor, passed back verbatim. |
Responses
| Status | Meaning |
|---|---|
200 | A page of patients and their requested settings keys. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
422 | keys is missing, empty or over 10 keys, or limit is outside 1 to 500, or cursor is too long. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
items | PatientSettingsItemSchema[] | yes | |
nextCursor | string | null | yes |
Updated 9 days ago