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.

OperationEndpoint
Get an org's rule settingsGET /api/settings/org
Replace an org's rule settingsPUT /api/settings/org
Get a patient's own rule settingsGET /api/patient/{id}/settings
Replace a patient's own rule settingsPUT /api/patient/{id}/settings
Merge keys into a patient's own rule settingsPATCH /api/patient/{id}/settings
List the tenant's patient rule settings by keyGET /api/patient-settings

GET /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

NameInRequiredDescription
projectquerynoAbsent: the tenant-wide row, which a patient with no project row reads.

Responses

StatusMeaning
200The settings.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
422project is empty or longer than 200 characters.

Response body

FieldTypeRequiredDescription
projectstring | nullyesThe project these settings are for; null for the tenant-wide row.
settingsobjectyesOpaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}.
createdbooleannoPUT ?ifAbsent=true only: whether this call created the row.

PUT /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

NameInRequiredDescription
projectquerynoAbsent: the tenant-wide row, which a patient with no project row reads.
ifAbsentquerynoCreate 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

FieldTypeRequiredDescription
resolvedAtstringno
settingsobjectyes

Responses

StatusMeaning
200The settings as stored, kept triggers included (with created under ifAbsent).
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
409A write resolved no later than the stored one (STALE_SETTINGS); nothing was written.
422settings is missing, is not a plain object or is over 64 KiB, or project or resolvedAt is invalid.

Response body

FieldTypeRequiredDescription
projectstring | nullyesThe project these settings are for; null for the tenant-wide row.
settingsobjectyesOpaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}.
createdbooleannoPUT ?ifAbsent=true only: whether this call created the row.

GET /api/patient/{id}/settings

Get 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

NameInRequiredDescription
idpathyesThe Signals patient id.

Responses

StatusMeaning
200The settings.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
404No such patient in this tenant.

Response body

FieldTypeRequiredDescription
patientIdstringyes
settingsobjectyesOpaque 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

Replace 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

NameInRequiredDescription
idpathyesThe Signals patient id.

Request body

FieldTypeRequiredDescription
resolvedAtstringno
settingsobjectyes

Responses

StatusMeaning
200The settings as stored.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
404No such patient in this tenant.
409A write resolved no later than the stored one (STALE_SETTINGS); nothing was written.
422settings is missing, is not a plain object or is over 64 KiB, or resolvedAt is invalid.

Response body

FieldTypeRequiredDescription
patientIdstringyes
settingsobjectyesOpaque 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

Merge 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

NameInRequiredDescription
idpathyesThe Signals patient id.

Request body

FieldTypeRequiredDescription
resolvedAtstringno
settingsobjectyes

Responses

StatusMeaning
200The settings as stored after the merge.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
404No such patient in this tenant.
409A write resolved no later than the stored one (STALE_SETTINGS); nothing was written.
422settings is missing, is not a plain object or is over 64 KiB (or would be once merged), or resolvedAt is invalid.

Response body

FieldTypeRequiredDescription
patientIdstringyes
settingsobjectyesOpaque to Signals beyond triggers; the triggers give the other keys their meaning. Example: {"bands":{"8867-4":{"low":50,"high":110}}}.

GET /api/patient-settings

List 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

NameInRequiredDescription
keysqueryyesThe top-level settings keys to return, comma-separated: residentLimits,bands.
limitquerynoPage size, 1 to 500. Defaults to 200.
cursorquerynoOpaque keyset cursor: a previous answer's nextCursor, passed back verbatim.

Responses

StatusMeaning
200A page of patients and their requested settings keys.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
422keys is missing, empty or over 10 keys, or limit is outside 1 to 500, or cursor is too long.

Response body

FieldTypeRequiredDescription
itemsPatientSettingsItemSchema[]yes
nextCursorstring | nullyes

Did this page help you?