`, valid for 7 days. The share starts only when that practitioner, signed in, posts both values to `POST /v1/invites/record-share/accept`.
- The record is already shared with that practitioner: nothing is sent, unless their account has no password yet, in which case the set-password email goes out again.
- Anything else (a User that is not a practitioner of this project, or a practitioner with full project access): nothing is written or sent.
- Each email is sent as the last step of the write. Map the email templates named above in the project's email configuration first.
- Do not enable practitioner sharing in projects whose practitioners use the carehub dashboard: its route guard checks resource types only, so a practitioner who only holds shared patients could see project-wide data there.
- A 409 with `invitation_not_configured` means the project has no default practitioner access policy. It needs project configuration, not a retry.
- A 429 means the patient already has 20 pending offers.
### Related person
- **Body:** `email`, `firstName`, `lastName`, `codes` (1 to 100 Observation codes, each letters, digits, `.` and `-` only), and optional `includeMedications` (defaults to `false`).
- **Gates**, checked before the address is looked up, in this order:
- patient sharing (`enabled` on `PUT /v1/patient-sharing/settings`) is on; it is off by default;
- `RELATED_PERSON_INVITATION_ENABLED` is not `false` (403 `Invitation is not enabled for this project.`, as for a practitioner);
- the project has a patient app URL;
- the patient has fewer than 20 pending related-person invites.
- **What happens, by address:**
- No User has the address: a pending share is created and the address gets a `RELATED_PERSON_INVITED` email with an accept link, `/accept-invite?invite=&code=`, valid for 7 days. Nothing else is created yet: the account is made when the link is accepted (`POST /v1/invites/record-share/accept` with a `password`).
- The address belongs to exactly one active related person of the project: a pending share is created and the address gets a `RELATED_PERSON_RECORD_SHARED` email with the same kind of link. The share starts when that related person, signed in, accepts it.
- Anything else (a patient, a practitioner, or a User that is not a related person of this project): nothing is written or sent.
- The pending share is a `draft` Consent holding only a hash of the one-time code. It grants nothing until it is accepted.
- `RELATED_PERSON_INVITED` and `RELATED_PERSON_RECORD_SHARED` carry `firstName`, `lastName`, `sharerName` (the patient's name), `invitationUrl` (the accept link) and `baseUrl`. A project whose email configuration maps neither sends `PATIENT_INVITE` and `PATIENT_ASSIGNMENT_REQUEST` instead, with `inviterName` set to the patient's name.
- A 429 means the patient already has 20 pending related-person invites.
### Both
- The answer is always `202 { "status": "sent" }`, whichever case applied, so it does not reveal whether the address has an account. If the email cannot be sent, everything the invite wrote is undone, and the answer is still 202.
- A 409 with `app_url_not_configured` means the project has no app URL for the recipient: the practitioner app, or the patient app for a related person.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/record-share' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"recipient": "practitioner",
"email": "max.mustermann@example.com",
"firstName": "Max",
"lastName": "Mustermann"
}'
```
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/record-share' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"recipient": "related-person",
"email": "max.mustermann@example.com",
"firstName": "Max",
"lastName": "Mustermann",
"codes": ["8480-6", "8462-4"],
"includeMedications": true
}'
```
- [Accept a patient's record share](/api/invites/accept-a-patient-s-record-share): Accepts a patient's record share from its email: a practitioner's `PRACTITIONER_PATIENT_SHARED` offer, or a related person's `RELATED_PERSON_INVITED` or `RELATED_PERSON_RECORD_SHARED` invite. From then on the share is in place. The invite decides how it is accepted.
**Auth:** bearer token of the Practitioner or RelatedPerson the invite names; none for an invite to a new address.
**Scope:** the caller's project (from the token); for a new address, the invite's project.
## Behaviour
- Send the `invite` and `code` values from the email's accept link as `inviteId` and `code`. `password` is only for a new related person; send `null` (or leave it out) otherwise.
- Every invite is single use and expires 7 days after it was sent. A used one answers 409, an expired one 410, and an unknown one or a wrong `code` 404, whoever calls.
- On success the invite's Consent becomes `active` and its grant is added to the recipient's membership, in one atomic write. The recipient's cached sessions are refreshed, so the new access applies on the next request.
- The share lasts until the patient ends it (`DELETE /v1/patient-sharing/shares/{consentId}`).
### A practitioner's offer
- Signed in as the practitioner the offer names; without a token the answer is 401.
- Gates: practitioner sharing must be on for the project, and `PRACTITIONER_INVITATION_ENABLED` must not be `false`.
- The share covers the patient's whole compartment. Observations, Communications, DocumentReferences, QuestionnaireResponses, ServiceRequests, Tasks and Appointments can be read, searched, created and updated; CommunicationRequests, Goals, CarePlans, Flags, EpisodeOfCare and DeviceUseStatements are read-only; the Patient can be read, searched and updated. Nothing can be deleted.
- A 409 with `practitioner_without_access_policy` means the caller has full project access, which a share would narrow.
- The answer is the practitioner share: `consentId`, `sharer`, `practitioner`, `startedAt`, `endsAt`.
### A related person's invite
- Gate: patient sharing must be on for the invite's project.
- The share covers the sharer's Observations with the invite's codes (read and search), and the sharer's Patient resource with contact details, identifiers and most other fields hidden.
- A share also covers a multi-value reading's group Observation when it covers every value the group repeats (systolic and diastolic for blood pressure, the waveform for an ECG, any part of an SpO2 or urine-strip reading), so the whole reading can be read and nothing more. The share's `codes` stay as the sharer chose them.
- **A new address** (`RELATED_PERSON_INVITED`): no token. Send a `password` that meets the password policy; without one the answer is a 422 with `password_required`. In one atomic write under the address's account lock, the account is made: a User scoped to the project, a RelatedPerson of the sharer, and a membership holding the built-in related-person base policy (read and search of its own RelatedPerson only, created the first time it is needed) and the share's grant. If the address has any account by now, nothing is written and the answer is a 409 with `address_has_account`. Sign in afterwards with the address and that password.
- **A related person of the project** (`RELATED_PERSON_RECORD_SHARED`): signed in as the related person the invite names; without a token the answer is 401, as another related person or in another project 404. The grant is added to their membership, keeping its base policy.
- The answer is the related-person share: `consentId`, `sharer`, `relatedPerson`, `codes`, `startedAt`, `endsAt`.
- A 409 with `sharing_not_configured` means the project lost its patient-sharing template; turn patient sharing on again.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"code": "",
"password": null
}'
```
A new related person, without a token:
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/record-share/accept' \
-H 'Content-Type: application/json' \
-d '{
"inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"code": "",
"password": "Ex4mple-Passw0rd"
}'
```
- [Invite a patient into my care](/api/invites/invite-a-patient-into-my-care): A signed-in practitioner invites a patient into their care, by email. A new address gets a patient account whose record is already shared with the inviter; a patient of the project gets an invite to accept.
**Auth:** bearer token of a Practitioner.
**Scope:** the caller's project (from the token).
## Behaviour
- **Gates**, checked before the address is looked up, in this order:
- practitioner sharing (`practitionerSharingEnabled` on `PUT /v1/patient-sharing/settings`) is on; it is off by default;
- `PATIENT_INVITATION_ENABLED` is not `false`;
- the project has a patient app URL;
- the project has a default patient access policy;
- the inviter's membership has an access policy (a membership with full project access is refused, because a share would narrow it);
- the inviter has fewer than 20 pending invites.
- **What happens, by address:**
- No User has the address: a patient account of the project is created with the default patient access policy, and its record is shared with the inviter, in one atomic write. The address gets a `PATIENT_INVITE` email with a set-password link on the patient app.
- The address belongs to exactly one active patient of the project: a pending invite is created and the address gets a `PATIENT_ASSIGNMENT_REQUEST` email with an accept link, `/accept-invite?invite=&code=`, valid for 7 days. The share starts only when that patient, signed in, posts both values to `POST /v1/invites/care/accept`.
- The patient already shares their record with the inviter: nothing is sent, unless their account has no password yet, in which case the set-password email goes out again.
- Anything else (a User that is not a patient of this project): nothing is written or sent.
- The answer is always `202 { "status": "sent" }`, whichever case applied, so it does not reveal whether the address has an account. If the email cannot be sent, everything the invite wrote is undone, and the answer is still 202.
- Each email is sent as the last step of the write. Map the email templates named above in the project's email configuration first.
- Do not enable practitioner sharing in projects whose practitioners use the carehub dashboard: its route guard checks resource types only, so a practitioner who only holds shared patients could see project-wide data there.
- A 409 with `app_url_not_configured` means the project has no patient app URL; `invitation_not_configured` means it has no default patient access policy; `practitioner_without_access_policy` means the inviter has full project access. None of these is fixed by retrying.
- A 429 means the practitioner already has 20 pending invites.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/care' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"email": "max.mustermann@example.com",
"firstName": "Max",
"lastName": "Mustermann"
}'
```
- [Accept a practitioner's care invite](/api/invites/accept-a-practitioner-s-care-invite): The signed-in patient accepts a practitioner's invite into their care from a `PATIENT_ASSIGNMENT_REQUEST` email. From then on their whole record is shared with the inviting practitioner.
**Auth:** bearer token of a Patient.
**Scope:** the caller's project (from the token).
## Behaviour
- Send the `invite` and `code` values from the email's accept link as `inviteId` and `code`.
- Gates: practitioner sharing must be on for the project, and `PATIENT_INVITATION_ENABLED` must not be `false`.
- Only the patient the invite names can accept it. The invite is single use and expires 7 days after it was sent.
- On success the invite's Consent becomes `active` and a grant for the caller's record is added to the practitioner's membership, in one atomic write. The practitioner's cached sessions are refreshed.
- The practitioner gets the access described on `POST /v1/invites/record-share/accept`: the patient's whole compartment, with no delete.
- The share lasts until the patient ends it (`DELETE /v1/patient-sharing/shares/{consentId}`).
- A 409 with `practitioner_without_access_policy` means the practitioner has full project access, which a share would narrow.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/invites/care/accept' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"code": ""
}'
```
- IotDevice
- [Get Pulsene MQTT settings](/api/iotdevice/get-pulsene-mqtt-settings): Returns the MQTT connection settings for a Pulsene MC01 device. The device calls this route on startup to learn which broker to connect to.
**Auth:** None at the HTTP level (no bearer token). The body must carry an `apiKey` that matches the key the device firmware ships with. A wrong or missing key is rejected with 401.
## Behaviour
- The body must contain `serialNumber` (non-empty string) and `apiKey` (non-empty string).
- Ovok does not look the device up. Any serial that passes the key check receives the same response shape: `mqtt.clientId` is the serial you sent, `username` and `password` are the fixed MC01 broker credentials, and `url` is the broker URL configured for the environment.
- `wifi` and `pairing` are not returned for this device family.
- The route answers `200`. It does not write anything.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/iot-device/pulsene/setup' \
-H 'Content-Type: application/json' \
-d '{ "serialNumber": "", "apiKey": "" }'
```
- Localization
- [Get project locales](/api/localization/get-project-locales): Returns the languages enabled for your project and its default language.
**Auth:** bearer token. You need `List:read` and `List:search` access, or be a project admin.
**Scope:** the caller's project (from the token).
## Behaviour
- The locale settings are stored as a FHIR `List` in your project.
- If the project has no locale settings yet, the route returns 404. Create them with `PATCH /locales`.
- Localization and content routes accept only the languages returned here.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/locales' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Set project locales](/api/localization/set-project-locales): Sets the languages enabled for your project and its default language. Creates the locale settings if the project has none.
**Auth:** bearer token. You need `List:create`, `List:read`, `List:update`, `List:delete` and `List:search` access, or be a project admin.
**Scope:** the caller's project (from the token).
## Behaviour
- The body replaces the whole setting. `languages` needs at least one language, and `defaultLanguage` must be one of them.
- For each language that is new compared with the previous setting, background jobs create AI translations of all localization keys and content items from the previous default language. Existing translations are not changed.
- Removing a language does not delete its localizations or content.
- Changing `defaultLanguage` does not move or translate anything by itself.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/locales' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "languages": ["en-US", "de-DE", "fr-FR"], "defaultLanguage": "en-US" }'
```
- Localization Keys
- [Get i18next resources for a language](/api/localization-keys/get-i18next-resources-for-a-language): Returns all localizations of one language as a nested i18next resource object. Apps load it to initialise i18next.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `language` must be one of the languages in your project's locale settings (`GET /locales`).
- Dot-separated keys are turned into nested objects: `home.screen.title` becomes `{ "home": { "screen": { "title": "..." } } }`.
- If a key is both a value and the parent of other keys, for example `home` and `home.title`, the nested object wins and the value of `home` is left out.
- At most 10,000 entries are included.
- The result per project and language is cached. A `PATCH` to this language becomes visible only after its background job has finished.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/localization/i18next/en-US' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Write i18next resources for a language](/api/localization-keys/write-i18next-resources-for-a-language): Writes many localizations of one language at once from a nested i18next resource object. The write runs in the background.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `language` must be one of the languages in your project's locale settings (`GET /locales`).
- The body is a nested object. Keys may contain only letters, digits, `_` and `-`; nesting builds dot-separated keys. Each value is either a string of 1 to 4,096 characters or another nested object.
- Keys in the body are created or overwritten. Keys that are not in the body are not changed. Nothing is deleted.
- The route answers `202 Accepted` with no body as soon as the job is queued. The values are written by a background job, and the cache for the language is cleared when it finishes.
- A second background job per project language creates AI translations of the default-language values for keys that have no translation in that language yet. Existing translations are not changed.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/localization/i18next/en-US' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "home": { "title": "Home", "subtitle": "Welcome back" } }'
```
- [List localizations with translations](/api/localization-keys/list-localizations-with-translations): Lists localization keys as pairs of the default-language value and its translation in a target language. Use it for translation screens that show the original next to the translation.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `target` must be one of the languages in your project's locale settings, and must not be the default language.
- Each result has `source` (the entry in the default language) and `target` (the entry in the target language) for the same key. `target` is missing when the key has no translation yet.
- Pairs are sorted by the target's `date`, newest first, falling back to the source's `date`. `_sort` is accepted but has no effect.
- `search` is a fuzzy match over both values, both keys and the target's author name.
- `_count` defaults to `10` and must be greater than 0. `_offset` defaults to `0`. `total` is the number of matching pairs before paging.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/localization/map/de-DE?search=home' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List localizations for a language](/api/localization-keys/list-localizations-for-a-language): Lists the localization keys and values of one language, with optional fuzzy search and paging.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `language` must be one of the languages in your project's locale settings (`GET /locales`).
- Results are sorted by `date`, newest first. `_sort` is accepted but has no effect.
- `search` is a fuzzy match over the value, the key and the author name.
- `_count` defaults to `10` and must be greater than 0. `_offset` defaults to `0`. `total` is the number of matching entries before paging.
- At most 10,000 entries per language are considered.
- The list per project and language is cached. Writes through these routes clear the cache for the language they change.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/localization/en-US?search=home&_count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get a localization](/api/localization-keys/get-a-localization): Returns the localization for one key in one language.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `language` must be one of the languages in your project's locale settings (`GET /locales`).
- `key` is a dot-separated path such as `home.screen.title`. It may contain letters, digits, `_`, `-` and `.`, and must not start with `.`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/localization/en-US/home.screen.title' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Delete a localization](/api/localization-keys/delete-a-localization): Deletes one key in one language, or in every language when you name the default language.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `language` must be one of the languages in your project's locale settings (`GET /locales`).
- If `language` is the project's default language, the key is deleted in every project language. Otherwise only that language's entry is deleted.
- Deleting a key that does not exist succeeds and changes nothing.
- The response has no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/localization/en-US/home.screen.title' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create or update a localization](/api/localization-keys/create-or-update-a-localization): Sets the value of one key in one language. Creates the localization if it does not exist yet.
**Auth:** bearer token.
**Scope:** the caller's project (from the token). Localizations are read and written with your token.
## Behaviour
- `language` must be one of the languages in your project's locale settings (`GET /locales`).
- `key` is a dot-separated path such as `home.screen.title`. It may contain letters, digits, `_`, `-` and `.`, and must not start with `.`.
- Ovok sets `author` to your profile. If more than one entry exists for this key and language, the first is kept and the others are deleted.
- After the write, a background job runs for every project language. It creates an AI translation of the default-language value for each language that has no entry for this key yet. Existing translations are not changed.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/localization/en-US/home.screen.title' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "value": "Home" }'
```
- MCP
- [MCP endpoint (POST only)](/api/mcp/mcp-endpoint-post-only): This MCP server is stateless: use POST.
- [MCP endpoint](/api/mcp/mcp-endpoint): Ovok's MCP server, for Claude or any MCP client: it sets up the project it is connected to, as one of the project's admins.
**Auth:** an access token from Ovok's MCP OAuth server, never a Medplum token. Clients find it the standard way:
1. A `GET`, `POST` or `DELETE` without a token answers 401 with `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"`.
2. That document names the authorization server, `/mcp`. Its metadata is at `/.well-known/oauth-authorization-server/mcp`.
3. The client registers itself at `/mcp/register`, sends the user to `/mcp/authorize` (PKCE S256), and exchanges the code at `/mcp/token`. The answer to the client carries `iss`, this authorization server's issuer (RFC 9207), on allow and on deny.
Sign-in and consent happen on the Ovok console. Only an admin of the project can connect a client, and never to the Super Admin project.
## Behaviour
- Streamable HTTP, stateless: send every JSON-RPC message with `POST`, one per request. A batch answers 400. There are no sessions: `GET` and `DELETE` answer 405 to a caller with a valid token, and 401 without one.
- `server/discover` (MCP 2026-07-28) answers the protocol versions this server speaks, its `tools` capability and its name. None of those versions is 2026-07-28 yet: start with `initialize`.
- `/mcp`, its OAuth routes and both MCP metadata documents answer with `Strict-Transport-Security: max-age=31536000; includeSubDomains`.
- Every request checks the token, then that its account is still an admin of the project. An account that is no longer an admin gets 403 at once, whatever the token's expiry. When that can't be read, the answer is 503: try again.
- Tools act on the project the connection was granted for:
- `get_project`;
- `get_settings`, `set_setting`, `set_setting_value`;
- `list_members`, `invite_member`;
- `list_apps` (without the apps' secrets), `create_app`;
- `get_signals`.
- Each tool runs the same service as the matching API route, with the same rules. A refused call answers a tool error carrying the route's status and error body.
- Limits:
- Each admin may send 300 messages a minute. Over that, the answer is 429 with `Retry-After`.
- Each tool allows 60 calls a minute per admin; `create_app` and `invite_member` allow 10. Over that, the tool error has status 429 and `retryAfterSec`.
- Tool errors carry the route's status and body for a refusal (4xx). A failure (5xx) is logged and answered without its detail.
- MCP calls are not API usage: like the console's own calls, they are left out of statistics and the plan's monthly request cap.
- Access tokens last an hour. Refresh tokens last 30 days, and each one works once: a refresh answers a new pair. A repeat within 30 seconds, such as parallel refreshes, gets a pair of its own. A refresh token used again later ends the connection, and so does revoking either token. A connection ends 90 days after its consent, however often it refreshes: connect again.
## Example
Add it to Claude Code, which signs in through the browser on first use:
```bash
claude mcp add --transport http ovok https://api.sandbox.ovok.com/mcp
```
- [MCP endpoint (POST only)](/api/mcp/mcp-endpoint-post-only-2): This MCP server is stateless: use POST.
- Me
- Me/Consent
- [Get legal consent](/api/me/consent/get-legal-consent): Returns the signed-in practitioner's legal consent: which terms they accepted, when, and whether the acceptance is still active. Use it on app load to decide whether to ask for the terms again.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read` and `Consent:search` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- `legal` is `null` when the practitioner has never accepted the terms in this project.
- `status` is `active` or `revoked`. Publishing new terms revokes every acceptance on an older version with `revokedReason: "tos-updated"`; withdrawing revokes it with `revokedReason: "withdrawn"`. Both reasons are `null` while the consent is active.
- `revokedAt` is when the revoke happened, or for `tos-updated` when the new terms were published.
- `termsUrl` is the terms page the practitioner accepted. It is `null` unless it is an `http(s)` URL or an app-relative path.
- `termsUpdatedAt` is when the accepted terms were last updated, `null` when that is not known.
- The published terms version is the one of the root project of your project tree: a child project follows its parent's terms.
- Answers are cached for a rolling day. Any consent write by the practitioner and any publish of new terms refreshes them right away.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/me/consent/legal' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{
"legal": {
"consentId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"status": "revoked",
"termsUrl": "https://app.example.com/legal/terms-and-conditions",
"termsUpdatedAt": "2026-09-01T08:00:00.000Z",
"acceptedAt": "2026-09-02T07:30:00.000Z",
"revokedAt": "2026-10-01T09:00:00.000Z",
"revokedReason": "tos-updated"
}
}
```
- [Accept or withdraw the terms](/api/me/consent/accept-or-withdraw-the-terms): Accepts or withdraws the terms for the signed-in practitioner and returns the resulting legal consent.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read`, `Consent:search`, `Consent:create` and `Consent:update` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- `termsAndConditionsConsent: true` records acceptance of the currently published terms. It creates the legal consent, or re-activates a revoked one, with a link to the terms page of your project's practitioner app and the time of acceptance.
- `termsAndConditionsConsent: false` revokes an active legal consent with `revokedReason: "withdrawn"`. With no active consent it changes nothing.
- Accepting again on the same terms version writes nothing.
- The terms value read by `GET /v1/slim/user/consents` changes in the same commit. Other consents are not changed.
- The response has the shape of `GET /v1/me/consent/legal`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/me/consent/legal' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "termsAndConditionsConsent": true }'
```
- [Get medical consent](/api/me/consent/get-medical-consent): Returns the signed-in practitioner's medical settings notifications consent, or `null` when it is not given. Use it on app load to decide whether to show the medical notifications prompt.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read` and `Consent:search` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- `medical` is `null` when the practitioner never gave the consent or withdrew it.
- Only withdrawing ends it. Unlike `GET /v1/slim/user/consents`, a newly published version does not turn it off here.
- `acceptedAt` is when it was given, `null` when that is not recorded.
- Answers are cached for a rolling day. Any consent write by the practitioner refreshes them right away.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/me/consent/medical' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{ "medical": { "consentId": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "acceptedAt": "2026-09-02T07:30:00.000Z" } }
```
- [Give or withdraw the medical consent](/api/me/consent/give-or-withdraw-the-medical-consent): Gives or withdraws the medical settings notifications consent for the signed-in practitioner and returns the resulting medical consent. Other consents are not changed.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read`, `Consent:search`, `Consent:create` and `Consent:update` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- `medicalSettingsNotificationsConsent: true` records the consent on the currently published version. `false` withdraws it.
- Sending the current value again writes nothing.
- The value read by `GET /v1/slim/user/consents` changes in the same commit.
- The response has the shape of `GET /v1/me/consent/medical`: `medical` is `null` after a withdrawal.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/me/consent/medical' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "medicalSettingsNotificationsConsent": true }'
```
- Organization Code Information
- [Email organization codes](/api/organization-code-information/email-organization-codes): Emails a user the tenant codes of every organization (project) they have an account in. Use it on a sign-in screen for users who forgot their organization code.
**Auth:** none.
## Behaviour
- The route always answers 202 with no body and does the work in the background, so the answer does not tell you whether the email has an account.
- The background job finds every account with this email, then looks up the tenant code of each project. If there are no accounts or no codes, no email is sent.
- The email lists each project's name and code. It uses the `PATIENT_ORGANIZATION_CODES` template when the first account found is a Patient, and `OVOK_ORGANIZATION_CODES` otherwise. Language and domain come from the request.
- The email address is lowercased.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/organizations/code/email' \
-H 'Content-Type: application/json' \
-d '{
"email": "max.mustermann@example.com"
}'
```
- [Get organization code](/api/organization-code-information/get-organization-code): Returns the tenant code of the caller's project. Users type the code on sign-in screens to choose their organization.
**Auth:** bearer token.
**Scope:** the caller's project (from the token).
## Behaviour
- The response holds `code` and `projectId`.
- If the project has no tenant code, the request fails with 400 (`Tenant code not found`).
- If more than one code row exists for a project, the most recently updated one is returned.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/organizations/code' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Patient sharing
- [Get patient sharing settings](/api/patient-sharing/get-patient-sharing-settings): Returns the caller's project settings for data sharing: whether patients may share their data with each other, and whether the patient and practitioner invites (`/v1/invites`) are on.
**Auth:** bearer token of a project admin.
**Scope:** the caller's project (from the token).
## Behaviour
- `enabled`: patient-to-patient sharing is on. Off unless an admin turned it on.
- `accessPolicyId`: the ID of the read-only template AccessPolicy every patient-to-patient share points at, or `null` while none has been created.
- `practitionerSharingEnabled`: the `/v1/invites` routes are on. Off unless an admin turned it on.
- `practitionerAlertDigest`: whether the clinician alert digest is on and how many hours apart it goes out. Off, every 6 hours, unless an admin set it.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-sharing/settings' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update patient sharing settings](/api/patient-sharing/update-patient-sharing-settings): Turns patient-to-patient sharing, and the patient and practitioner invites (`/v1/invites`), on or off for the caller's project.
**Auth:** bearer token of a project admin.
**Scope:** the caller's project (from the token).
## Behaviour
- `enabled` is required. Turning it on creates the read-only sharing template AccessPolicy, or brings an existing one up to date, in the same atomic write as the setting. The template lets a recipient read and search the sharer's Observations with the shared codes, and read the sharer's Patient resource with contact details, identifiers and most other fields hidden.
- Turning `enabled` off stops new invites and redemptions. Existing shares stay until they are ended.
- `enabled` also lets a signed-in patient share Observation codes with a related person by email (`POST /v1/invites/record-share` with `"recipient": "related-person"`). A new address gets a related-person account when it accepts, with a built-in base policy that reads only its own RelatedPerson; it is created the first time it is needed. Map `RELATED_PERSON_INVITED` and `RELATED_PERSON_RECORD_SHARED`, or the `PATIENT_INVITE` and `PATIENT_ASSIGNMENT_REQUEST` templates they fall back to: an invite whose email cannot be sent is undone.
- `practitionerSharingEnabled` does the same for the patient and practitioner invites, with the practitioner share's template. Leave it out or send `null` to keep its current value.
- Both are off by default. The response is the settings after the write, as `GET /v1/patient-sharing/settings` returns them.
- With `practitionerSharingEnabled` on, a signed-in patient can create a practitioner account (with the project's default practitioner access policy) for a new address, and a practitioner can create a patient account, each holding the share. Make sure that policy gives a new practitioner nothing a patient should not hand out. Map the `PATIENT_INVITE`, `PATIENT_ASSIGNMENT_REQUEST`, `PRACTITIONER_INVITED_BY_PATIENT` and `PRACTITIONER_PATIENT_SHARED` email templates first: an invite whose email cannot be sent is undone.
- Do not turn on `practitionerSharingEnabled` in projects whose practitioners use the carehub dashboard: its route guard checks resource types only, so a practitioner who only holds shared patients could see project-wide data there.
- `practitionerAlertDigest` turns the clinician alert digest on or off: `{ "enabled": true, "everyHours": 6 }`, where `everyHours` is 1, 6, 12 or 24. Leave `everyHours` out to keep the saved hours (6 until set). Leave the whole field out, or send `null`, to keep the digest as it is.
- Switching it on needs Signals annotations (`SIGNALS_ANNOTATE_OBSERVATIONS`), `enabled` and `practitionerSharingEnabled` all on; otherwise the write is refused with 409 `SETTING_NOT_AVAILABLE`. A write that only keeps it on is not checked, so sharing can still be turned off. While any of the three is off, no digest goes out.
- Every `everyHours`, each practitioner on an active practitioner share gets one email listing their patients with new Signals alerts: the patient's name, how many new alerts, and a link to the patient's alerts in the dashboard. It carries no reading or value, and nothing goes out when there are no new alerts.
- It counts alerts from the moment it was switched on, never the backlog before. Switching it off, or one of its prerequisites going off, forgets where it was, so switching it on again starts afresh.
- Each digest covers alerts up to an hour before it goes out: alerts reach FHIR through a flush that can lag, and an alert that arrives more than an hour late is not counted.
- Map the `PRACTITIONER_ALERT_DIGEST` email template first.
- A 409 without a code means the project's settings changed during the write. Read the settings again and retry.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-sharing/settings' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "enabled": true, "practitionerSharingEnabled": null, "practitionerAlertDigest": { "enabled": true, "everyHours": 6 } }'
```
- [Create a share invite](/api/patient-sharing/create-a-share-invite): The signed-in patient creates a one-time invite to share Observations with the given codes with another patient. Set `includeMedications` to `true` to also share patient-scoped MedicationStatements and MedicationAdministrations. Hand the `inviteId` and `code` to the other patient, who accepts with `POST /v1/patient-sharing/invites/redeem`.
**Auth:** bearer token of a Patient.
**Scope:** the caller's project (from the token).
## Behaviour
- Patient sharing must be on for the project (`PUT /v1/patient-sharing/settings`).
- `codes`: 1 to 100 Observation codes, each 1 to 64 letters, digits, `.` or `-`. Duplicates are removed.
- `includeMedications`: optional, defaults to `false`. When true, the recipient can read the sharer's MedicationStatements and MedicationAdministrations until the share ends.
- `endsAt` must be `null`: a share lasts until it is ended. A date is refused for now.
- The invite is stored as a draft `Consent`. Only a SHA-256 hash of `code` is stored, so `code` is returned once, in this response.
- The invite expires 15 minutes after it is created (`expiresAt`).
- A patient can hold at most 10 unexpired invites at once.
- A 429 means the patient already holds 10 unexpired invites.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-sharing/invites' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "codes": ["8480-6", "8462-4"], "endsAt": null, "includeMedications": true }'
```
- [Accept a share invite](/api/patient-sharing/accept-a-share-invite): The signed-in patient accepts another patient's share invite, and from then on can read what it shares.
**Auth:** bearer token of a Patient.
**Scope:** the caller's project (from the token).
## Behaviour
- Patient sharing must be on for the project.
- The invite is single use, expires 15 minutes after it was created, and cannot be accepted by the patient who made it.
- On success the invite's `Consent` becomes `active` and names the caller as recipient, and a grant is added to the caller's membership, in one atomic write. The caller's cached sessions are refreshed, so the new access applies on the next request.
- The grant lets the caller read and search the sharer's Observations with the shared codes, and read the sharer's Patient resource with contact details, identifiers and most other fields hidden.
- A share also grants a multi-value reading's group Observation when it covers every value the group repeats (systolic and diastolic for blood pressure, the waveform for an ECG, any part of an SpO2 or urine-strip reading), so the whole reading can be read and nothing more. The share's `codes` stay as the sharer chose them.
- A 409 that says your account changed meanwhile can be retried as is.
- A 503 means sharing is on but its template AccessPolicy is missing.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-sharing/invites/redeem' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"inviteId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"code": ""
}'
```
- [List shares](/api/patient-sharing/list-shares): Lists the signed-in patient's active shares in both directions, the practitioners their whole record is shared with, and the related persons they share codes with. For a signed-in related person (a carer), lists the shares patients gave them.
**Auth:** bearer token of a Patient or a RelatedPerson.
**Scope:** the caller's project (from the token).
## Behaviour
- `outgoing`: the caller's active patient-to-patient shares (Consents where the caller is the sharer), including the `includeMedications` choice.
- `incoming`: what is shared with the caller, read from the grants on the caller's own membership, since those decide what the caller can see. Each share includes its `includeMedications` choice. A grant whose Consent cannot be read is still listed, so it can be ended.
- `practitioners`: the caller's active record shares with practitioners.
- `relatedPersons`: the caller's active shares with related persons (carers), each with its `codes` and `includeMedications` choice.
- `received`: for a related person, the active shares patients gave them: the sharing patient (`sharer`), the shared `codes`, `includeMedications` and `startedAt`. Only their own: another carer's shares never show. Empty for a patient.
- A related person gets only `received`; the other lists are empty.
- Names are the display names of the Patient, Practitioner and RelatedPerson profiles in the project.
- A practitioner gets 403.
- Each Consent search returns at most 100 entries; there is no paging.
- Pending invites (drafts) are not listed.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-sharing/shares' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [End a share](/api/patient-sharing/end-a-share): Ends a share, cancels a pending invite, or declines a practitioner's invite. A related person (a carer) leaves a share they received. Access stops at once.
**Auth:** bearer token of a Patient or a RelatedPerson.
**Scope:** the caller's project (from the token).
## Behaviour
- Who may call it, by `consentId`:
- a patient-to-patient share: the sharer or the recipient;
- a pending patient-to-patient invite: the sharer (this cancels it);
- a share of the caller's record with a practitioner, or a practitioner's pending invite to the caller: the patient.
- a share of the caller's codes with a related person, or its pending invite: the patient;
- a share a patient gave the caller as their related person: the related person (see below).
- A practitioner gets 403.
- Every grant bound to the Consent is removed from the members who hold it, and the Consent is set to `inactive`, in one atomic write. The holders' cached sessions are refreshed.
- Calling it again on an ended share only sweeps any grants left behind, so retrying is safe.
- If the records keep changing during the write, it retries up to three times, then answers 409. Retry the call.
- Returns `204 No Content`.
## A related person leaving a share
- The Consent is set to `inactive`, as when the patient ends it, and its grant leaves the caller's own membership, in one atomic write. The caller's cached sessions are refreshed.
- The membership keeps its base policy. One that had lost it gets it back, so it never reads as full project access.
- `404` when the share is not one the caller received, for example another carer's or a patient-to-patient share. It never says whose it is.
- `409` when the share already ended, or a record changed during the write. Read the list again and retry.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/patient-sharing/shares/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Payload CMS API Keys
- [List the project's CMS API keys](/api/payload-cms-api-keys/list-the-project-s-cms-api-keys): Lists the API keys of your current project's CMS content. A key unlocks public CMS delivery (`/v1/public/cms/...`) of this project's tenant only. The keys themselves are never returned.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- `keys` is newest first. Each has `id`, `name`, `prefix` (the key's first 12 characters, to tell keys apart), `createdAt` and `isDefault`.
- Every project starts with one key, `isDefault: true` with `id` `default` and `createdAt: null`: the key public delivery took before keys were per project. It works until you revoke it. Its `prefix` is only its first 4 characters: the same key serves every project that has not revoked it.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/cms/api-keys' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create a CMS API key](/api/payload-cms-api-keys/create-a-cms-api-key): Creates an API key for public CMS delivery (`/v1/public/cms/...`) of your current project's tenant. The answer carries the key itself, once: it is stored only as a hash and cannot be shown again.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- `name` is 1 to 64 characters, trimmed.
- The key starts with `ovok_cms_`. Send it as `x-api-key`, `Authorization: Bearer` or `?apiKey=`, with the tenant it belongs to (`x-ovok-tenant-code`, `?tenant=`, `x-ovok-medplum-project-id` or `?projectId=`). Naming another project's tenant answers 401.
- A project holds at most 20 keys, the default key included: one more returns 409 `CMS_API_KEY_LIMIT`.
- A 409 without a code means the project changed while the server wrote. Retry.
- The answer is 201.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/cms/api-keys' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "name": "Marketing site" }'
```
- [Revoke a CMS API key](/api/payload-cms-api-keys/revoke-a-cms-api-key): Revokes one of your current project's CMS API keys. Public delivery stops taking it at once.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- `id` is a key's `id` from `GET /v1/cms/api-keys`; `default` revokes the default key.
- A key the project does not hold returns 404 `CMS_API_KEY_NOT_FOUND`.
- A 409 means the project changed while the server wrote. Retry.
- Public responses a CDN already cached may still be served for up to a minute.
- The answer is 204.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/cms/api-keys/default' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Payload CMS Public Delivery
- [List published documents of a public collection](/api/payload-cms-public-delivery/list-published-documents-of-a-public-collection): Lists the published documents of a CMS collection for one tenant, in one language, one page at a time. Use it to show content such as release notes or articles in an app or website.
**Auth:** one of the following, checked in this order:
- The CMS public API key, in the `x-api-key` header, as `Authorization: Bearer `, or as the `apiKey` query parameter.
- No key, for collections configured as keyless (by default `legal-pages` and `translations`).
- A signed-in Ovok session (bearer token), which may only read its own tenant.
**Scope:** the tenant you name, by tenant code (`x-ovok-tenant-code` header or `tenant` query parameter) or by project id (`x-ovok-medplum-project-id` header or `projectId` query parameter). Headers win over query parameters, and a tenant code wins over a project id. If you name neither, a signed-in session reads its own tenant. Each Ovok deployment has one set of content; there is no environment to choose.
## Behaviour
- Any collection except the `users` and `tenants` system collections can be read.
- Only documents with status `published` are returned. The response is the CMS list envelope (`docs`, `totalDocs`, `page`, `limit`, and so on).
- `locale` is a language tag such as `de` or `en-US`. Without it, the CMS default locale is used. Missing translations fall back as configured in the CMS.
- `page` defaults to `1` and is limited to 1 to 100. `limit` defaults to `20` and is limited to 1 to 50. Values outside those ranges are clamped; values that are not whole numbers fall back to the default.
- `sort` is a top-level field name, optionally prefixed with `-` for descending order, for example `-publishedAt`. Without it, the CMS default order is used.
- Ovok also has a shared tenant whose published documents are added to every tenant's list. Where both have a document with the same `slug`, the tenant's own document wins. If either tenant has more than 200 published documents in the collection, only the tenant's own documents are returned.
- Responses are cached by Ovok for up to 60 seconds. A request that names a tenant gets `Cache-Control: public, s-maxage=60, stale-while-revalidate=300` and a `Vary` on the tenant and API key headers. A request that names no tenant gets `Cache-Control: no-store`. Error responses carry neither.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/public/cms/collections/release-notes/items?tenant=my-medical-project&locale=de&sort=-publishedAt&limit=10' \
-H 'x-api-key: '
```
- [Get a published document by slug](/api/payload-cms-public-delivery/get-a-published-document-by-slug): Returns one published document of a CMS collection by its slug. Use it for stable public pages and deep links, such as terms and conditions or a privacy policy.
**Auth:** one of the following, checked in this order:
- The CMS public API key, in the `x-api-key` header, as `Authorization: Bearer `, or as the `apiKey` query parameter.
- No key, for collections configured as keyless (by default `legal-pages` and `translations`).
- A signed-in Ovok session (bearer token), which may only read its own tenant.
**Scope:** the tenant you name, by tenant code (`x-ovok-tenant-code` header or `tenant` query parameter) or by project id (`x-ovok-medplum-project-id` header or `projectId` query parameter). Headers win over query parameters, and a tenant code wins over a project id. If you name neither, a signed-in session reads its own tenant. Each Ovok deployment has one set of content; there is no environment to choose.
## Behaviour
- Any collection except the `users` and `tenants` system collections can be read.
- Only a document with status `published` is returned. The response is the document itself, with the fields its collection defines.
- `slug` must start with a lowercase letter or digit and contain only lowercase letters, digits, `-`, `_` and `.`, up to 128 characters.
- `locale` is a language tag such as `de` or `en-US`. Without it, the CMS default locale is used. Missing translations fall back as configured in the CMS.
- If the tenant has no published document with this slug, Ovok returns the shared tenant's document with that slug, when one exists.
- Responses are cached by Ovok for up to 60 seconds. A request that names a tenant gets `Cache-Control: public, s-maxage=60, stale-while-revalidate=300` and a `Vary` on the tenant and API key headers. A request that names no tenant gets `Cache-Control: no-store`. Error responses carry neither.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/public/cms/collections/legal-pages/items/terms-and-conditions?tenant=my-medical-project&locale=en-US'
```
- [List published items of a content type](/api/payload-cms-public-delivery/list-published-items-of-a-content-type): Lists the published items of a user-defined content type for one tenant. First-class collections are read with `GET /v1/public/cms/collections/{collectionSlug}/items` instead.
**Auth:** one of the following:
- The CMS public API key, in the `x-api-key` header, as `Authorization: Bearer `, or as the `apiKey` query parameter.
- A signed-in Ovok session (bearer token), which may only read its own tenant.
**Scope:** the tenant you name, by tenant code (`x-ovok-tenant-code` header or `tenant` query parameter) or by project id (`x-ovok-medplum-project-id` header or `projectId` query parameter). Headers win over query parameters, and a tenant code wins over a project id. If you name neither, a signed-in session reads its own tenant. Each Ovok deployment has one set of content; there is no environment to choose.
## Behaviour
- Returns the CMS `content-items` whose content type has the slug `contentTypeSlug` and whose status is `published`, in the CMS list envelope.
- At most 100 items are returned. There is no paging, sorting or locale selection on this route.
- Responses are cached by Ovok for up to 60 seconds. A request that names a tenant gets `Cache-Control: public, s-maxage=60, stale-while-revalidate=300` and a `Vary` on the tenant and API key headers. A request that names no tenant gets `Cache-Control: no-store`. Error responses carry neither.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/public/cms/faq/items?tenant=my-medical-project' \
-H 'x-api-key: '
```
- Projects
- [Get current project settings](/api/projects/get-current-project-settings): Returns the settings of your current project: the on/off settings and the text settings such as app URLs and default access policies.
**Auth:** bearer token. The caller must be a Practitioner, a project admin, or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- Settings are read from `Project.setting[]` by name.
- `settings` always has every on/off key. A key that is not stored, or not stored as a boolean, is `false`.
- `values` always has every text key. A key that is not stored, or is blank, is `null`.
- `DEFAULT_PATIENT_ACCESS_POLICY` is read from `Project.defaultPatientAccessPolicy`, as `AccessPolicy/`: the policy patient registration and patient invites give a new patient.
- Entries of `Project.setting[]` with other names are not returned.
## Saved and effective values
`settings` cannot tell a switch turned off from one never saved. Two records, with every on/off key, can:
- `overrides`: the saved value, `true` or `false`, or `null` when none is saved (or it is not stored as a boolean).
- `effectiveSettings`: what Ovok applies. The saved value, else the default below, and off while the feature lacks what it needs (the column on the right).
| Key | Default | Also needs |
| --- | --- | --- |
| `PATIENT_LOGIN_ENABLED`, `PRACTITIONER_LOGIN_ENABLED`, `RELATED_PERSON_LOGIN_ENABLED` | on | |
| `PATIENT_INVITATION_ENABLED` | on | `DEFAULT_PATIENT_ACCESS_POLICY`. |
| `PRACTITIONER_INVITATION_ENABLED`, `RELATED_PERSON_INVITATION_ENABLED` | on | |
| `PATIENT_REGISTRATION_ENABLED` | on | `DEFAULT_PATIENT_ACCESS_POLICY`, naming a policy that can be read. |
| `PRACTITIONER_REGISTRATION_ENABLED` | off | `DEFAULT_PRACTITIONER_ACCESS_POLICY` (or `CLINICIAN_INVITE_ACCESS_POLICY`): an AccessPolicy of this project. |
| `CLINICIAN_INVITE_ON_BUSINESS_EMAIL` | off | Effective `PATIENT_REGISTRATION_ENABLED`, and the default practitioner access policy as above. |
| `CONTENT_ENABLED`, `MAILING_ENABLED` | off | Markers the Console sets; Ovok does not act on them. |
| `SIGNALS_SEND_AUTO` | off | A Signals tenant of the project's own. Observations created through FHIR go to it, and a resident's first one enrols the resident in Signals; ingest readings go there on their own. |
| `SIGNALS_ANNOTATE_OBSERVATIONS` | as `SIGNALS_SEND_AUTO` | A Signals tenant of the project's own. Signals' alerts and episodes are written into the project as `DetectedIssue` and `Flag`, and an alert's reading gets its `interpretation`. Project roles need read on `DetectedIssue` and `Flag` to see them. |
| `SIGNALS_MTLS_ENABLED` | off | A Signals tenant of the project's own, and an environment whose edge forwards client certificates. Calls into Signals through `/v1/signals/api/*` must present a registered client certificate (`/v1/signals/certs`), and Signals presents its own client certificate on every webhook to the tenant. |
- App URLs are not folded in: they are in `values`, and a flow that needs a missing one reports it, for example an invite answers 409 `app_url_not_configured`.
- Some routes need more. The sharing invites (`/v1/invites`) also need practitioner sharing on, set through the patient-sharing settings.
- With `PRACTITIONER_LOGIN_ENABLED` off, a practitioner who is a project admin keeps refreshing an open session, so they can turn it back on.
- A default access policy that cannot be read at that moment counts as missing, as it does for the flows themselves.
- Every key is read from the first `Project.setting[]` entry of its name.
## App URLs
`PATIENT_APP_URL` and `PRACTITIONER_APP_URL` are the app roots that links in emails are built on: `https://app.example.com` gives `https://app.example.com/setpassword//`.
- Resolution order, per audience: the project's setting, then the parent project's, then the legacy setting (`PATIENT_SIGNUP_URL` or `CLINICIAN_DASHBOARD_URL`, on the project then its parent), then the request `Origin` for flows that allow it, then the deployment default.
- For set-password and invite links, only the origin of `PATIENT_SIGNUP_URL` is used: `https://app.example.com/register` gives `https://app.example.com`, and `vitalwise://register` gives `vitalwise://`. Set `PATIENT_APP_URL` if the patient app lives under a path.
- The continue-as-patient link (a business-address sign-up turned into a clinician invite) uses `PATIENT_SIGNUP_URL` in full whenever it is set, ahead of `PATIENT_APP_URL`.
- An app URL is an https URL on any host (http only on localhost), or an app deep link `scheme://[host][/path]`: `vitalwise://` gives `vitalwise:///setpassword//`. A web URL on this API's own host is refused, and a stored one is skipped when an email is sent.
- Only the canonical form is stored and used, without a trailing slash. Userinfo, a query, a fragment, an opaque `scheme:path`, and web, script or local schemes used as a deep link (`javascript:`, `data:`, `file:` and others) are refused on write and skipped on send.
- An invite with no app URL for its audience answers 409 `app_url_not_configured` and creates nothing.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/project/settings' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update a project setting](/api/projects/update-a-project-setting): Turns one on/off setting of your current project on or off, for example `PRACTITIONER_INVITATION_ENABLED`.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- `:key` must be one of the on/off keys returned in `settings` by `GET /v1/project/settings`. It may be URL-encoded.
- Writes the entry into `Project.setting[]`, adding it when missing. Every other entry is kept as it is.
- The write only succeeds if the project did not change since the server read it; otherwise it answers 409.
- The response is the full settings envelope after the write, as `GET /v1/project/settings` returns it.
- An unknown `:key` returns 400 `UNKNOWN_SETTING` with the accepted keys.
- `SIGNALS_SEND_AUTO` and `SIGNALS_ANNOTATE_OBSERVATIONS` also switch their wiring before the setting is saved: Medplum's `Subscription` for send-auto, Signals' `ovok-annotations` subscriber for annotations. Nothing is saved if that fails (502 `SETTING_WIRING_FAILED`). Turning either on for a project without its own Signals tenant answers 409 `SETTING_NOT_AVAILABLE`; a concurrent change of the same switch answers 409 too. While `SIGNALS_ANNOTATE_OBSERVATIONS` has no saved value it follows `SIGNALS_SEND_AUTO`, so switching send-auto also switches annotations' wiring.
- `SIGNALS_MTLS_ENABLED` switches the project's calls into Signals and Signals' webhooks to it to mutual TLS, in the order that keeps the stricter side first: on, Ovok starts refusing calls without a registered client certificate before Signals is switched; off, Signals is switched first. Turning it on with no registered certificate (`POST /v1/signals/certs`), without a Signals tenant of the project's own, or where the environment's edge forwards no client certificates answers 409 `SETTING_NOT_AVAILABLE`. A Signals that does not keep the switch answers 502 `SETTING_WIRING_FAILED`, and nothing is saved.
- Read the project again and retry on 409.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/project/settings/PRACTITIONER_INVITATION_ENABLED' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "enabled": true }'
```
- [Update a project text setting](/api/projects/update-a-project-text-setting): Sets one text setting of your current project, such as an app URL or a default access policy, or removes it with `null`.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- `:key` must be one of the text keys returned in `values` by `GET /v1/project/settings`. It may be URL-encoded.
- `value` is trimmed and checked for the key's kind:
- App URL keys (`PATIENT_APP_URL`, `PRACTITIONER_APP_URL`, `PATIENT_SIGNUP_URL`, `CLINICIAN_DASHBOARD_URL`): see App URLs below. The canonical form is stored.
- Access policy keys (`DEFAULT_PATIENT_ACCESS_POLICY`, `DEFAULT_PRACTITIONER_ACCESS_POLICY`, `CLINICIAN_INVITE_ACCESS_POLICY`): `AccessPolicy/` of an AccessPolicy in this project.
- `null` removes the entry. Every other entry of `Project.setting[]` is kept as it is.
- `DEFAULT_PATIENT_ACCESS_POLICY` is written to `Project.defaultPatientAccessPolicy`, not to `Project.setting[]`. Removing it turns patient registration and patient invitations off: see `effectiveSettings` in `GET /v1/project/settings`.
- The write only succeeds if the project did not change since the server read it; otherwise it answers 409.
- The response is the full settings envelope after the write, as `GET /v1/project/settings` returns it.
## App URLs
`PATIENT_APP_URL` and `PRACTITIONER_APP_URL` are the app roots that links in emails are built on: `https://app.example.com` gives `https://app.example.com/setpassword//`.
- Resolution order, per audience: the project's setting, then the parent project's, then the legacy setting (`PATIENT_SIGNUP_URL` or `CLINICIAN_DASHBOARD_URL`, on the project then its parent), then the request `Origin` for flows that allow it, then the deployment default.
- For set-password and invite links, only the origin of `PATIENT_SIGNUP_URL` is used: `https://app.example.com/register` gives `https://app.example.com`, and `vitalwise://register` gives `vitalwise://`. Set `PATIENT_APP_URL` if the patient app lives under a path.
- The continue-as-patient link (a business-address sign-up turned into a clinician invite) uses `PATIENT_SIGNUP_URL` in full whenever it is set, ahead of `PATIENT_APP_URL`.
- An app URL is an https URL on any host (http only on localhost), or an app deep link `scheme://[host][/path]`: `vitalwise://` gives `vitalwise:///setpassword//`. A web URL on this API's own host is refused, and a stored one is skipped when an email is sent.
- Only the canonical form is stored and used, without a trailing slash. Userinfo, a query, a fragment, an opaque `scheme:path`, and web, script or local schemes used as a deep link (`javascript:`, `data:`, `file:` and others) are refused on write and skipped on send.
- An invite with no app URL for its audience answers 409 `app_url_not_configured` and creates nothing.
- An unknown `:key` returns 400 `UNKNOWN_SETTING` with the accepted keys. A web app URL on this API's own host returns 400 `APP_URL_NOT_ALLOWED`. A value that is not valid for the key returns 422 `INVALID_SETTING_VALUE`.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/project/settings/values/PRACTITIONER_APP_URL' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "value": "https://app.example.com" }'
```
- [List administered projects](/api/projects/list-administered-projects): Lists every project you administer, with the tenant code you need to switch to it. Every other `/v1/projects` route answers about the single project of your token; use this one to build a project picker.
**Auth:** bearer token. The caller must be a Practitioner, a project admin, or hold the System Owner access policy. You do not need to be an admin of your current project.
**Scope:** your own user's Practitioner memberships across all projects, kept only where the membership is an admin one.
## Behaviour
- One row per project, in membership order, even when you hold two memberships on one project.
- `page` (from 0, default 0) and `count` (1 to 100, default 20) page over the projects. `total` counts the projects you administer, not your memberships.
- `tenantCode` is `null` for a project that has none. `name` is `null` when the project can no longer be read; the row is kept.
- `isMainProject` is `true` for a project with no parent, `false` for a child, and `null` when the hierarchy could not be read.
- `parentProjectId` is set only when the parent is also a project you administer; otherwise it is `null`.
- To switch, pass `tenantCode` to `POST /v1/auth/tenant/Practitioner/login/token`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/projects?page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List current project members](/api/projects/list-current-project-members): Lists the Practitioner members of your current project, one page at a time.
**Auth:** bearer token. The caller must be a Practitioner, a project admin, or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- Only memberships with a Practitioner profile are returned; patient, bot and client memberships are left out.
- Filters: `accessPolicyId` (the membership's access policy), `profileId` (a Practitioner id) and `userId`.
- `page` (from 0, default 0) and `count` (1 to 100, default 20) page the results. `total` is the exact number of matches.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/projects/me/members?page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Invite a Practitioner to the project](/api/projects/invite-a-practitioner-to-the-project): Adds a Practitioner to your current project and emails them a link to set their password.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token). The project setting `PRACTITIONER_INVITATION_ENABLED` must be on.
## Behaviour
- `email` is trimmed and lowercased. `firstName` and `lastName` default to `New` and `Member`; `admin` defaults to `false`.
- Creates the User (when the address has no account yet), the Practitioner and the membership in one write.
- The invitee is emailed a link to set a password, built on the project's practitioner app URL (the project's `PRACTITIONER_APP_URL`, then the parent project's, then the legacy `CLINICIAN_DASHBOARD_URL`, then your request's `Origin` when CORS allows it, then the deployment default). The response has `pending: true` and `existingAccount: false`.
- An address that can already sign in (it has a password, or belongs to another project) gets the membership but no email, and the response has `existingAccount: true`.
- If the email cannot be sent, the new account is removed again and the request fails.
- `access` sets the membership's `access[]` entries. Each must name an AccessPolicy of this project. With `access`, the membership's base `accessPolicy` is the project's `DEFAULT_PRACTITIONER_ACCESS_POLICY` setting.
- A member with this email already exists on the project: 409. Setting `access` on a project with no default practitioner access policy: 409 `invitation_not_configured`. No practitioner app URL resolves: 409 `app_url_not_configured`, and nothing is created.
- Practitioner invitations disabled on the project: 403.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/projects/me/members' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"email": "max.mustermann@example.com",
"firstName": "Max",
"lastName": "Mustermann",
"admin": false
}'
```
- [Get a project member](/api/projects/get-a-project-member): Reads one Practitioner member of your current project.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token). A membership of another project answers 404.
## Behaviour
- `emailVerified` is `true` once the member has used an emailed set-password link, and `null` when the User cannot be read.
- `pending` is always `false` on this route.
- The route requires a Practitioner membership; any other membership type is refused with 400.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/projects/me/members/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update a project member](/api/projects/update-a-project-member): Changes a Practitioner member of your current project: their admin flag, their `access[]` entries, or both.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token). A membership of another project answers 404.
## Behaviour
- `admin`: `true` or `false` sets the flag; `null` leaves it as it is.
- `access`: replaces the membership's `access[]` entries; an empty array removes them. Omit it to leave them as they are. Each entry must name an AccessPolicy of this project. A membership without a base `accessPolicy` cannot have its entries removed, because Medplum would then grant access to the whole project.
- `versionId`: pass the `meta.versionId` you read. If the membership changed since, the request answers 409. A concurrent write that lands first also answers 409.
- A request that changes nothing returns the member unchanged.
- Demoting the last admin of the project is refused.
- After the change, Ovok renews its cached session data for every session of the member. Medplum applies the change on the member's next request.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/v1/projects/me/members/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "admin": true }'
```
- [Remove a project member](/api/projects/remove-a-project-member): Removes a Practitioner from your current project.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token). A membership of another project answers 404.
## Behaviour
- Deletes the membership and its Practitioner profile. The User is deleted only when it has no other membership in any project.
- All or nothing: if one delete fails, the others are undone and the request fails.
- Removing the last admin of the project is refused.
- The response is `{ "success": true }`.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/projects/me/members/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get current project features](/api/projects/get-current-project-features): Returns the Medplum features (`Project.features`) enabled on your current project, such as `bots` or `cron`.
**Auth:** bearer token. The caller must be a Practitioner, a project admin, or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- Values are returned as stored, without checking them against the list `PATCH` accepts. An empty array means no features are enabled.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/projects/me/features' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update current project features](/api/projects/update-current-project-features): Replaces the Medplum features (`Project.features`) of your current project with the list you send.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- The list replaces the stored one; it is not merged. Send every feature you want enabled. Sending the same list twice has the same result.
- Each value must be one of the FHIR `Project.features` codes.
- The write only succeeds if the project did not change since the server read it; otherwise it answers 409.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/v1/projects/me/features' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "features": ["bots", "cron", "websocket-subscriptions"] }'
```
- Public Resource Access
- [Get a public resource](/api/public-resource-access/get-a-public-resource): Reads a FHIR resource through its public token, without a bearer token. Use it to share one resource, such as a form or a document, with people who have no Ovok account.
**Auth:** none. The public token in the path is the credential: anyone with it can read the resource.
## Behaviour
- A resource becomes public when it gets a token in `meta.extension`, with the URL `https://api.ovok.com/fhir/StructureDefinition/public-resource-token`. Use `PATCH /public/{resourceType}/{id}` to give a resource a token.
- The token names exactly one resource. The response is that resource as stored, including its `meta.extension`.
- A token stops working when the resource's token is replaced or deleted, or when the resource is deleted.
## Example
```bash
curl 'https://api.sandbox.ovok.com/public/example.jwt.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Change public resource token](/api/public-resource-access/change-public-resource-token): Gives a resource a new public token, so it can be read with `GET /public/{token}`. If the resource already has a token, the old one is replaced and stops working.
**Auth:** bearer token of a project admin.
## Behaviour
- The resource must be in the caller's project or one of its sub-projects. A resource of any other project, the parent project included, answers `403` and is left unchanged; an unknown id answers `404`.
- The token is written to the resource's `meta.extension` with the URL `https://api.ovok.com/fhir/StructureDefinition/public-resource-token`. Other extensions are kept.
- The response is `{ token, resource }`: the new token and the updated resource.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/public/DocumentReference/87ea5dfc-8b8e-384d-8489-79496e706390' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{
"token": "...",
"resource": {
"resourceType": "DocumentReference",
"id": "87ea5dfc-8b8e-384d-8489-79496e706390",
"meta": {
"extension": [
{ "url": "https://api.ovok.com/fhir/StructureDefinition/public-resource-token", "valueString": "..." }
]
},
...
}
}
```
- [Delete public resource token](/api/public-resource-access/delete-public-resource-token): Removes the public token from a resource, so it can no longer be read with `GET /public/{token}`. The resource itself is kept.
**Auth:** bearer token of a project admin.
## Behaviour
- The resource must be in the caller's project or one of its sub-projects. A resource of any other project, the parent project included, answers `403` and is left unchanged; an unknown id answers `404`.
- Removes the `meta.extension` entry with the URL `https://api.ovok.com/fhir/StructureDefinition/public-resource-token`. Other extensions are kept.
- Calling it on a resource without a token succeeds.
- The response is `{ token: null, resource }` with the updated resource.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/public/DocumentReference/87ea5dfc-8b8e-384d-8489-79496e706390' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Reset Password
- [Send reset password email](/api/reset-password/send-reset-password-email): Sends a password reset email to a Patient, a RelatedPerson (carer) or a Practitioner. The answer is the same whether or not an account exists, so the route cannot be used to find out which emails are registered.
**Auth:** none.
**Scope:** for a Patient or RelatedPerson, the project that owns `clientId`. For a Practitioner, the account is found by email across projects.
## Behaviour
- `type` is `Patient`, `RelatedPerson` or `Practitioner`. `clientId` is required when `type` is `Patient` or `RelatedPerson` and is ignored for a Practitioner.
- The response is always a FHIR `OperationOutcome` saying "If the user exists, a password reset email has been sent." It is returned for unknown emails, unknown client IDs and accounts that could not be mailed.
- When the account exists, Ovok creates a reset request, which replaces any earlier open reset request for the user, and emails the user. Patients and RelatedPersons get the `PATIENT_RESET_PASSWORD` template and Practitioners the `RESET_PASSWORD` template.
- The email carries a link `/setpassword//` plus the request `id` and `secret`. The app URL is the project's patient app URL for a Patient or RelatedPerson, and its practitioner app URL for a Practitioner; if none is set, the request's `Origin` is used when it is an allowed one.
- A Practitioner who is a member of more than one project gets a link to the Ovok platform app instead of a project's app URL.
- If no app URL can be found, the email still goes out, without a link. The `id` and `secret` in it can be sent to `POST /v2/auth/reset-password/process`.
- If a Practitioner has several accounts, the first one found is used.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v2/auth/reset-password' \
-H 'Content-Type: application/json' \
-d '{
"email": "max.mustermann@example.com",
"clientId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"type": "Patient"
}'
```
- [Reset user password with the information from the email.](/api/reset-password/reset-user-password-with-the-information-from-the-email): Sets a new password using the `id` and `secret` from a reset email. Use it when your app handles the reset itself instead of sending the user to the emailed link.
**Auth:** none. The reset request `id` and `secret` are the credential.
## Behaviour
- The `id` and `secret` come from the email sent by `POST /v2/auth/reset-password`. The `password` is the new password.
- The password must have at least 12 characters, not counting spaces at either end, and must not be on Ovok's list of common and breached passwords. Any character is allowed and none is required. A refused password answers 422 with the error on `password`.
- An invite link (from `POST /auth/invite` or a practitioner invite) sets a password for 7 days after it was sent. After that it answers 410 `This invite link has expired. Ask for a new invite.`, and inviting the user again sends a fresh link. Reset links are not limited this way.
- A request can be used once. Ovok marks it used before it changes the password, so a request whose password change then fails cannot be retried and the user must ask for a new email.
- Setting the password also marks the user's email as verified, because the secret came by email.
- The response is a minimal `User` with `resourceType`, `id` and `email`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v2/auth/reset-password/process' \
-H 'Content-Type: application/json' \
-d '{
"id": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"secret": "k3J9xQ2mV7",
"password": "Ex4mple-Passw0rd"
}'
```
- Signals
- [List the project's client certificates](/api/signals/list-the-project-s-client-certificates): Lists the client certificates registered for your current project. With `SIGNALS_MTLS_ENABLED` on, every call into Signals through `/v1/signals/api/*` must present one of them.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy. A client credential cannot read or change them.
**Scope:** the caller's project (from the token).
## Behaviour
- Each certificate is known by `sha256`, its SHA-256 fingerprint in lowercase hex. Ovok never holds a private key.
- A project holds at most two: the one in use and one to rotate to.
- A certificate past `notAfter` stays listed until it is removed, but calls presenting it are refused.
- `environment` says what this Ovok environment can do: `issues` (a CA to issue from a CSR), `registers` (a CA it trusts for registration) and `forwardsCertificates` (an edge that passes client certificates on, which `SIGNALS_MTLS_ENABLED` needs). Check it before offering an action that would answer 501 or 409.
- A project without a Signals tenant of its own answers 409 `SIGNALS_TENANT_NOT_OWN`.
## Example
```bash
curl 'https://api.sandbox.ovok.com/v1/signals/certs' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Register a client certificate](/api/signals/register-a-client-certificate): Registers a client certificate for your current project. Calls into Signals may then present it, and must once `SIGNALS_MTLS_ENABLED` is on.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy. A client credential cannot register a certificate for itself.
**Scope:** the caller's project (from the token).
## Behaviour
- Send the certificate as PEM in `certificate`. Only its first certificate is read. Never send the private key: it stays with your client.
- The certificate must be valid now, not a CA certificate, for client authentication (or have no extended key usage), and issued by a CA your Ovok environment trusts. Otherwise 422 `CERTIFICATE_NOT_ACCEPTED`, with the reason.
- An environment with no CA set up for client certificates answers 501 `FEATURE_NOT_CONFIGURED`.
- The same certificate twice answers 409 `CERTIFICATE_ALREADY_REGISTERED`; a third certificate 409 `CERTIFICATE_LIMIT_REACHED`.
- The answer is 201 with the registered certificate, and `Location` names it.
- To rotate: register the new certificate, move your clients to it, then remove the old one.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d "{ \"certificate\": $(jq -Rs . < client.crt) }"
```
- [Issue a client certificate from a CSR](/api/signals/issue-a-client-certificate-from-a-csr): Issues a client certificate for your current project from a certificate signing request (CSR), and registers it. Calls into Signals may then present it, and must once `SIGNALS_MTLS_ENABLED` is on.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy. A client credential cannot issue a certificate for itself.
**Scope:** the caller's project (from the token).
## Behaviour
- Make a key and a CSR on your side, and send the CSR as PEM in `csr`. The private key never leaves your client.
- The key must be an EC key on P-256 or P-384, or an RSA key of at least 2048 bits, and the CSR's signature must verify. Otherwise 422 `CSR_NOT_ACCEPTED`, with the reason.
- Ovok's CA signs a certificate for client authentication only, valid for one year. Its subject is `CN=` and its subject alternative name `urn:ovok:signals-tenant:`. Nothing else in the CSR is taken over.
- The certificate counts towards the project's two: a third answers 409 `CERTIFICATE_LIMIT_REACHED`.
- An environment with no CA set up to issue answers 501 `FEATURE_NOT_CONFIGURED`. If its CA has expired, Ovok registers nothing and answers 500 `INTERNAL_ERROR`.
- The answer is 201 with the registered certificate and its PEM in `certificate`, and `Location` names it.
- To rotate: issue a new certificate, move your clients to it, then remove the old one.
## Example
```bash
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
-keyout client.key -out client.csr -subj "/CN=client"
curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d "{ \"csr\": $(jq -Rs . < client.csr) }" | jq -r .certificate > client.crt
```
- [Remove a client certificate](/api/signals/remove-a-client-certificate): Removes one of your current project's client certificates. From then on, calls presenting it are refused, even while it was the project's only one and `SIGNALS_MTLS_ENABLED` is on.
**Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy.
**Scope:** the caller's project (from the token).
## Behaviour
- `:sha256` is the certificate's fingerprint as `GET /v1/signals/certs` lists it.
- An unknown fingerprint answers 404 `CERTIFICATE_NOT_FOUND`.
- The answer is 204 with no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/signals/certs/3f6c0d2a9b8e7f1c4d5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f80912' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Signals API - Alerts: Alerts raised by evaluation. An alert opens on a breach, deduplicates on its `TRIGGER:` key while it stays open, and closes when a trigger resolves it.
- [List alerts, or the episodes they were folded into](/api/signals-api---alerts/list-alerts-or-the-episodes-they-were-folded-into): The dashboard view.
By default this is one row per breach, in v1's alert shape plus every nest alert field, inside v1's paginate envelope (`items`, `totalItems`, `page`, `totalPages`, …) with nest's `nextCursor` beside it. Page with v1's `page` and `limit` (a page may start at most 10000 rows in), or walk with `cursor`: pass `nextCursor` back verbatim. `sort` is v1's `time-desc` (the default) or `time-asc`; `ids` narrows to those patients. It works whether or not the tenant has `episodicAlerts`. Without `project` it is tenant-wide: a per-facility view must send `project`, which keeps only patients stamped with it.
`?episodes=true` answers with episodes instead, as `{items, nextCursor}`: one row per clinical event, which opens on the first breaching reading, absorbs the rest, and closes on recovery, on going stale, or by hand. That grain REQUIRES `project`. It defaults to the tenant's `feedCodes` (`PATCH /api/tenant`), every code when it lists none; alerts have no code default.
`codes`, `since` and `acknowledged` filter either grain. `until`, `page` and `ids` are alerts only: sending one with `episodes=true` is a 422, not a filter that silently did nothing. `status` reads ACTIVE/RESOLVED for alerts and OPEN/CLOSED for episodes.
Episodes are newest first by `sort`: `openedAt`, the default, or `lastFiringAt`, the newest firing reading (the opening, for an episode that has none). `since` and the cursor use the same time. `openedAt` never changes, so walking every page lists each episode once. On `lastFiringAt` an episode that fires mid-walk moves above the cursor: it is never listed twice, but that walk misses it. A `sort` value from the other grain is a 422.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_alerts:read`. Project admins have every capability; client applications get no admin bypass.
- ovok sets `project` to your project, so you can leave it out.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), name them with `patientId` or `ids`, each one you can read, at most 100. Signals then pages over just those patients, so pages and totals stay true. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Get one alert, or one episode with its readings](/api/signals-api---alerts/get-one-alert-or-one-episode-with-its-readings): The path segment is an alert id, or an episode id with `episodes=true`. An alert reads whether or not the tenant has `episodicAlerts`.
An episode comes with its summary, its acknowledgement and every value recorded for its code while it ran. The series starts at the first breaching reading. A long episode returns a capped series and sets `truncated`.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_alerts:read`. Project admins have every capability; client applications get no admin bypass.
- ovok sets `project` to your project, so you can leave it out.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the alert's patient must be one you can read: ovok reads the alert first. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Acknowledge an alert, or an episode](/api/signals-api---alerts/acknowledge-an-alert-or-an-episode): The path segment is an alert id, or an episode id with `episodes=true`. Acknowledging closes it: an alert resolves, an episode ends its alerting window, and the next breaching reading opens a new one. The patient's triggers decide what else closing does (their `onAck` hooks). Under the default pack, acknowledging an open out-of-bed alert (103214-3) also silences the absence under way.
Idempotent: acknowledging again returns the original time and actor. Acknowledging one that already closed only stamps the acknowledgement.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_alerts:update`. Project admins have every capability; client applications get no admin bypass.
- ovok sets `project` to your project, so you can leave it out.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the alert's patient must be one you can update: ovok reads the alert first. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Signals API - Clients: API credentials and their webhook subscriptions.
- [List users](/api/signals-api---clients/list-users): The tenant's API clients, newest first, in v1's paginate envelope (`page`, `limit` defaulting to 10) with nest's `nextCursor`. `role` and `name` filter as in v1.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_clients:read`. Project admins have every capability; client applications get no admin bypass.
- [Create a user](/api/signals-api---clients/create-a-user): Mints an API client. `clientId` and `secret` are the Basic credential, chosen by the caller and never returned. `role` may be v1's lowercase. A SUBSCRIBER needs `webhookUrl` and at least one event. It is on `eventSchema` 2 unless the body says 1: on 2 its first Standard Webhooks signing secret is returned this once as `signingSecret`; on 1 it needs `webhookSecret` (v1 called it `secret`). `reach` is `attached` (default: the patients attached to it, as v1's) or `all` (every patient of the tenant, those enrolled later included).
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`, `signals_events:read`. Project admins have every capability; client applications get no admin bypass.
- Only subscribers are created through ovok, on event schema 2. ovok generates their id and Signals login, which they never use, and Signals generates the webhook signing secret.
- 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.
- [Get one user](/api/signals-api---clients/get-one-user): Without its secret, which is not retrievable.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_clients:read`. Project admins have every capability; client applications get no admin bypass.
- [Update a user](/api/signals-api---clients/update-a-user): Sets the name, webhook target, signing secret, events, event schema, reach or credential secret.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`, `signals_events:read`. Project admins have every capability; client applications get no admin bypass.
- Only subscribers are changed through ovok. Their `role`, `eventSchema`, `clientId`, `secret` and `webhookSecret` can't be sent.
- 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.
- [Delete a user](/api/signals-api---clients/delete-a-user): Revokes the credential at once and drops its undelivered webhook events.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:delete`. Project admins have every capability; client applications get no admin bypass.
- Only subscribers are deleted through ovok.
- 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.
- [Read the webhook endpoint](/api/signals-api---clients/read-the-webhook-endpoint): The URL, whether it is `enabled`, `failing` or `disabled` (and why), when its current run of failures began, and its newest delivered and failed attempts. Five days of failures with no delivery, or one 410, disable it.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:read`. Project admins have every capability; client applications get no admin bypass.
- [Enable the webhook endpoint](/api/signals-api---clients/enable-the-webhook-endpoint): Resumes deliveries of new events. It re-queues nothing: events held while it was disabled go out only through `POST /api/events/redeliver?status=held`. Enabling an enabled endpoint changes nothing.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Disable the webhook endpoint](/api/signals-api---clients/disable-the-webhook-endpoint): Stops deliveries. Queued events and new ones are held, not dropped, for a redeliver once it is enabled again. Disabling a disabled endpoint keeps its first reason.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Send a test event](/api/signals-api---clients/send-a-test-event): Sends a signed `webhook.test` event (`{ event, subscriber, sentAt }`) now, with every header a real delivery carries, and answers what the receiver did. It is not queued, retried or listed, and it works on a disabled endpoint, so a receiver can be checked before it is enabled.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Rotate the webhook signing secret](/api/signals-api---clients/rotate-the-webhook-signing-secret): Mints a new Standard Webhooks signing secret (`whsec_` and 32 random bytes) and returns it this once. Every delivery carries `webhook-id` and `webhook-timestamp`; once the subscriber has a secret it also carries `webhook-signature`, so a receiver verifies with the Standard Webhooks library. The secret it replaces keeps signing until `previousSecretExpiresAt` (24 h), so `webhook-signature` holds both and the receiver switches with no gap. Each rotation keeps only the secret it replaces, so rotate again only once the receiver uses the new one. The first call mints the subscriber's first secret. A MANAGER rotates any subscriber of its tenant; a SUBSCRIBER only its own.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass.
- 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.
- Signals API - Events: Every webhook event queued, with how its delivery went, and sending it again: the safety net after a receiver outage.
- [List webhook events](/api/signals-api---events/list-webhook-events): Every event addressed to the caller, oldest first and keyset paged by `cursor`, each with its delivery status and payload: expired, failed and held ones too. An event is listed once it is two minutes old, so a page never moves past one a slower transaction has yet to commit. Filter by `types`, `status`, `patientId`, or (for a MANAGER) `subscriberId`.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_events:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), name them with `patientId`, each one you can read, at most 100. Signals then pages over just those patients, so pages and totals stay true. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [List a delivery's attempts](/api/signals-api---events/list-a-delivery-s-attempts): Each POST made for it, oldest first: when, how long, the status code or the error, and the first 2 KB of the answer.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_events:read`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Redeliver events](/api/signals-api---events/redeliver-events): Queues the oldest 1 000 deliveries in `status` (default `failed`) queued since `since` to be sent again, each with a fresh retry ladder: the same `webhook-id`, so receivers dedupe, and a new `webhook-timestamp`. An alert is sent whatever its age. Deliveries to a disabled endpoint, and ones being sent right now, are skipped. While it answers `queued: 1000`, call it again for the next ones.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Redeliver one event](/api/signals-api---events/redeliver-one-event): Queues this delivery to be sent now, whatever its status, with a fresh retry ladder: the same `webhook-id` and a new `webhook-timestamp`. An alert is sent whatever its age.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass.
- 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.
- Signals API - Health: Liveness plus the pipeline check that alarms when readings arrive and nothing alerts, or alerts queue and nothing is delivered.
- [Liveness](/api/signals-api---health/liveness): Unauthenticated, always 200: the HTTP status reports that the process is serving, not that its dependencies are well, because this route gates container liveness. `healthy` is false while the database does not answer (`db.ok`); page on it.
### Through ovok
- **Who can call it:** any caller with an ovok access token, or a client id and secret. It needs no capability.
- Signals API - Observations: Submitting readings. This is the hot path: one POST per reading (or a batch), judged by the patient's triggers in force (its own over its home's) before the response returns unless the tenant is in async mode.
- [Submit a reading by patient refId](/api/signals-api---observations/submit-a-reading-by-patient-refid): The patient is `patientRefId` in the body, else `subject.reference` (`Patient/`).
The body is a FHIR R4 Observation: `code`, `value[x]` (any of FHIR R4's eleven) or `dataAbsentReason`, and a combined device sample's vitals as `component[]` (each `code`, `value[x]`, optional `dataAbsentReason`). The clinical time is `effectiveDateTime`, `effectiveInstant` or `effectivePeriod.start`, else `issued`, else the server's receipt; `device` is `{reference, display}`; the first `identifier`'s `value` is stored as v1's `refId`. Other FHIR elements (`meta`, `extension`, `performer`, `interpretation`, `referenceRange`, …) are accepted and ignored. v1's `observedAt` (it wins over `effective[x]`), `refId`, string `dataAbsentReason` and `device.id` still work. A node with `dataAbsentReason` and no value is judged as carrying no value, and the rules read the reason as `absent`. `valueSampledData` is judged by its latest sample and stored whole, and the rules read every sample as `samples`. A `valueDateTime`, on the reading or a component, is judged and aggregated as epoch ms (`valueNumber`) and listed as sent. A `valueBoolean` is judged as 1 or 0. A `valueTime` is judged as ms since midnight, a `valuePeriod` as its length in ms (none while open or without an offset), a `valueRatio` as its quotient, and each is also kept as text (`valueString`); a `valueRange` is judged as the text `low..high`.
**History is never judged.** A reading whose `category` has a coding the tenant names as history (its `historyCategories`; the default pack's: `batch-data`, `statistics`, `presence-batch`, `derived`) is stored and deduplicated like any other, answered with no alerts, and never judged nor read by the rules.
The caller must be one of the patient's submitters, admins included: a known patient it is not attached to is a 403, an unknown one a 404 with type `PATIENT_NOT_FOUND`.
**Idempotent.** A reading is named by its first `identifier` (`system|value`), else by its clinical time, code, device and `refId`. A resend of one stored within the last hour is a 409 `DUPLICATE_READING` whose `data.observationId` is the stored reading, and is neither stored nor evaluated again. A reading with neither an identifier nor a clinical time is not deduplicated.
Concurrent requests are batched server-side. With `Prefer: respond-sync` evaluation finishes first and the reply adds `alertIds`, `alerts` (`[{id, code}]`), `resolvedAlertIds` and `ruleCoverage`; without it `mode` is `async` and alerts are delivered by webhook.
### Through ovok
- **Who can call it:** Submitter apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_observations:create`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Each reading counts its patient as monitored for billing.
- [List a patient's readings](/api/signals-api---observations/list-a-patient-s-readings): Newest first by clinical time, in v1's envelope `{items, total, page, pageSize, totalPages}` with nest's `nextCursor`. `from`, `to` and `code` (comma-separated) filter as in v1; `category` (comma-separated) keeps the readings carrying any of those FHIR category codes. With `from`, a reading whose clinical time is more than an hour ahead of when it was stored is not found: the read skips the storage older than that, so it never waits on it. `pageSize` defaults to 10; above 200 it needs both `from` and `to`, and then reaches 10000. A page may start at most 10000 rows in; walk further with `cursor`.
Each item is a flat timeline entry (`code`, `valueNumber`, `observedAt`, `category`, `valueSampledData`, `components`, `effectiveStart`, `effectiveEnd`, `deviceId`, …) with v1's `_id`, `id`, `patient`, `valueQuantity` and `createdAt` beside it. `fields=code,valueNumber` returns exactly those keys instead.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_observations:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can read. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Submit a reading for a patient id](/api/signals-api---observations/submit-a-reading-for-a-patient-id): `subject` is ignored: the path names the patient.
The body is a FHIR R4 Observation: `code`, `value[x]` (any of FHIR R4's eleven) or `dataAbsentReason`, and a combined device sample's vitals as `component[]` (each `code`, `value[x]`, optional `dataAbsentReason`). The clinical time is `effectiveDateTime`, `effectiveInstant` or `effectivePeriod.start`, else `issued`, else the server's receipt; `device` is `{reference, display}`; the first `identifier`'s `value` is stored as v1's `refId`. Other FHIR elements (`meta`, `extension`, `performer`, `interpretation`, `referenceRange`, …) are accepted and ignored. v1's `observedAt` (it wins over `effective[x]`), `refId`, string `dataAbsentReason` and `device.id` still work. A node with `dataAbsentReason` and no value is judged as carrying no value, and the rules read the reason as `absent`. `valueSampledData` is judged by its latest sample and stored whole, and the rules read every sample as `samples`. A `valueDateTime`, on the reading or a component, is judged and aggregated as epoch ms (`valueNumber`) and listed as sent. A `valueBoolean` is judged as 1 or 0. A `valueTime` is judged as ms since midnight, a `valuePeriod` as its length in ms (none while open or without an offset), a `valueRatio` as its quotient, and each is also kept as text (`valueString`); a `valueRange` is judged as the text `low..high`.
**History is never judged.** A reading whose `category` has a coding the tenant names as history (its `historyCategories`; the default pack's: `batch-data`, `statistics`, `presence-batch`, `derived`) is stored and deduplicated like any other, answered with no alerts, and never judged nor read by the rules.
The caller must be one of the patient's submitters, admins included: a known patient it is not attached to is a 403, an unknown one a 404 with type `PATIENT_NOT_FOUND`.
**Idempotent.** A reading is named by its first `identifier` (`system|value`), else by its clinical time, code, device and `refId`. A resend of one stored within the last hour is a 409 `DUPLICATE_READING` whose `data.observationId` is the stored reading, and is neither stored nor evaluated again. A reading with neither an identifier nor a clinical time is not deduplicated.
Concurrent requests are batched server-side. With `Prefer: respond-sync` evaluation finishes first and the reply adds `alertIds`, `alerts` (`[{id, code}]`), `resolvedAlertIds` and `ruleCoverage`; without it `mode` is `async` and alerts are delivered by webhook.
### Through ovok
- **Who can call it:** Submitter apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_observations:create`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Each reading counts its patient as monitored for billing.
- [Submit several readings for one patient](/api/signals-api---observations/submit-several-readings-for-one-patient): `{observations: []}`, each as `POST /api/observation/:patientId` takes it. In one transaction, evaluated in the order given. Answers v1's array, one entry per reading in request order: the reading as stored, or for a resend the 409 `DUPLICATE_READING` error body in its place. An array has nowhere to carry the ingest outcome, so a caller that needs `alertIds` posts them singly.
The body is a FHIR R4 Observation: `code`, `value[x]` (any of FHIR R4's eleven) or `dataAbsentReason`, and a combined device sample's vitals as `component[]` (each `code`, `value[x]`, optional `dataAbsentReason`). The clinical time is `effectiveDateTime`, `effectiveInstant` or `effectivePeriod.start`, else `issued`, else the server's receipt; `device` is `{reference, display}`; the first `identifier`'s `value` is stored as v1's `refId`. Other FHIR elements (`meta`, `extension`, `performer`, `interpretation`, `referenceRange`, …) are accepted and ignored. v1's `observedAt` (it wins over `effective[x]`), `refId`, string `dataAbsentReason` and `device.id` still work. A node with `dataAbsentReason` and no value is judged as carrying no value, and the rules read the reason as `absent`. `valueSampledData` is judged by its latest sample and stored whole, and the rules read every sample as `samples`. A `valueDateTime`, on the reading or a component, is judged and aggregated as epoch ms (`valueNumber`) and listed as sent. A `valueBoolean` is judged as 1 or 0. A `valueTime` is judged as ms since midnight, a `valuePeriod` as its length in ms (none while open or without an offset), a `valueRatio` as its quotient, and each is also kept as text (`valueString`); a `valueRange` is judged as the text `low..high`.
**History is never judged.** A reading whose `category` has a coding the tenant names as history (its `historyCategories`; the default pack's: `batch-data`, `statistics`, `presence-batch`, `derived`) is stored and deduplicated like any other, answered with no alerts, and never judged nor read by the rules.
The caller must be one of the patient's submitters, admins included: a known patient it is not attached to is a 403, an unknown one a 404 with type `PATIENT_NOT_FOUND`.
**Idempotent.** A reading is named by its first `identifier` (`system|value`), else by its clinical time, code, device and `refId`. A resend of one stored within the last hour is a 409 `DUPLICATE_READING` whose `data.observationId` is the stored reading, and is neither stored nor evaluated again. A reading with neither an identifier nor a clinical time is not deduplicated.
Concurrent requests are batched server-side. With `Prefer: respond-sync` evaluation finishes first and the reply adds `alertIds`, `alerts` (`[{id, code}]`), `resolvedAlertIds` and `ruleCoverage`; without it `mode` is `async` and alerts are delivered by webhook.
### Through ovok
- **Who can call it:** Submitter apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_observations:create`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Each reading counts its patient as monitored for billing.
- Signals API - Patient config: v1's config writes addressed by a list of patient ids. A trigger is stored as sent in the patient's settings, where it judges its code; one without logic is rejected and reported. Reads are POSTs here too — a thousand ids do not fit in a query string.
- [Write one config to many patients](/api/signals-api---patient-config/write-one-config-to-many-patients): Applies the same triggers, flags and metadata to every id named. An id may be the Signals id or the `refId`.
Unknown ids are reported in `misses[]` rather than failing the batch. `modifiedCount` counts patients where a row actually changed; `status.triggerWrites` gives the row counts behind it. Trigger `metadata` is MERGED and left untouched when absent.
Send `resolvedAt` (the instant the configuration was COMPUTED, not sent) to have this push refused rather than applied when the patient already carries a configuration resolved strictly later. Refusal is a silent no-op reported as `staleIgnoredCount`, never an error. Omitting it applies the push unconditionally.
### 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.
- A patient stamped with another project is refused.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Write a different config to each of many patients](/api/signals-api---patient-config/write-a-different-config-to-each-of-many-patients): The per-patient form, each entry with its own triggers, flags, `metadata` and `resolvedAt`. `results[]` has v1's `{id, matched, modified}` per entry; `staleIgnored` and `misses` are additions.
### 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.
- A patient stamped with another project is refused.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Read the config status of many patients](/api/signals-api---patient-config/read-the-config-status-of-many-patients): Each patient's `configUpdatedAt` and trigger codes, so a caller can confirm a push landed without re-reading every trigger; `triggerFingerprints` adds what each rule says.
Exactly one row per requested id, in the order asked. An id that resolves to nothing answers `refId: null` with no codes, as v1 did.
A POST because the id list is the request; it writes nothing.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_config:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can read. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Signals API - Patients: Patients and their alerting flags. `refId` is the caller's own identifier.
- [List patients](/api/signals-api---patients/list-patients-2): Scoped to what the caller may see: a MANAGER gets the tenant, a SUBMITTER or SUBSCRIBER only the patients it is attached to. Newest first.
v1's paginate envelope, driven by `page` and `limit` (default 10). A page may start at most 10000 rows in; past that, walk with the keyset `cursor`: pass `nextCursor` back verbatim, and `null` means the last page.
### Through ovok
- **Who can call it:** Manager apps and Submitter apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_patients:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), name them with `ids`, each one you can read, at most 100. Signals then pages over just those patients, so pages and totals stay true. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Create patients](/api/signals-api---patients/create-patients): Upserts on `refId`: posting a patient that already exists updates it rather than duplicating it, so a replayed provisioning run is safe. Each entry's `config` — flags and triggers — is applied in the same call, and `metadata` is merged.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_patients:update`. Project admins have every capability; client applications get no admin bypass.
- ovok adds your project's submitter to each new patient and stamps `metadata.project` with your project. Sending `config` also needs `signals_config:update` and `signals_silence:update`. New patients count toward your plan's monitored-patient cap.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Resolve refIds to Signals ids](/api/signals-api---patients/resolve-refids-to-signals-ids): An object from each `patientRefId` this tenant holds to its Signals id. A refId the tenant does not hold is left out rather than failing the request.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_patients:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), name them with `patientRefId`, each one you can read, at most 100. Signals then pages over just those patients, so pages and totals stay true. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Get one patient](/api/signals-api---patients/get-one-patient): The patient with its config, triggers keyed by code. A SUBMITTER or SUBSCRIBER reads only patients it is attached to.
### Through ovok
- **Who can call it:** Manager apps and Submitter apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_patients:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can read. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Update a patient](/api/signals-api---patients/update-a-patient): Only the fields present are changed; `metadata` is merged, not replaced. Answered with the v1 document.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_patients:update`. Project admins have every capability; client applications get no admin bypass.
- When you send `submitters` or `metadata`, ovok keeps your project's submitter and stamp in them. Sending `alertsPaused`, `alertIfEmpty`, `alertIfNote` or `alertInactiveDays` also needs `signals_config:update` and `signals_silence:update`.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient, and one a `refId` in the body names, must be ones you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Delete a patient](/api/signals-api---patients/delete-a-patient): Deletes the patient with its triggers, alerts, episodes and readings. This can't be undone through the API.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_patients:delete`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can delete. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [List a submitter's patients](/api/signals-api---patients/list-a-submitter-s-patients): The ids of the patients in this tenant the submitter may post readings for.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_associations:read`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Attach patients to a submitter](/api/signals-api---patients/attach-patients-to-a-submitter): Grants the client permission to post readings for those patients. Unknown patient ids are skipped, so a caller can re-post a superset of ids without a 404.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_associations:update`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Detach a patient from a submitter](/api/signals-api---patients/detach-a-patient-from-a-submitter): The submitter may no longer post readings for the patient.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_associations:update`. Project admins have every capability; client applications get no admin bypass.
- Your project's own submitter stays attached to its patients.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [List a subscriber's patients](/api/signals-api---patients/list-a-subscriber-s-patients): The ids of the patients in this tenant the subscriber reads and receives alerts for.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_associations:read`. Project admins have every capability; client applications get no admin bypass.
- 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.
- [Attach patients to a subscriber](/api/signals-api---patients/attach-patients-to-a-subscriber): Grants the client permission to read those patients' records and receive their alert webhooks. Unknown patient ids are skipped, so a caller can re-post a superset of ids without a 404.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_associations:update`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), every patient the body names must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Detach a patient from a subscriber](/api/signals-api---patients/detach-a-patient-from-a-subscriber): The subscriber no longer reads the patient's records or receives its alerts.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_associations:update`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Signals API - 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.
- [Get a patient's own rule settings](/api/signals-api---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?, 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
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_config:read`. Project admins have every capability; client applications get no admin bypass.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can read. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- [Replace a patient's own rule settings](/api/signals-api---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?, 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
- **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.
- `resolvedAt` may be at most 5 minutes ahead of now.
- If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), the patient must be one you can update. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a `refId`; ovok asks Signals which patient a Signals id is.
- Signals API - Tenants: Tenant-level feature switches.
- [Get the caller's tenant](/api/signals-api---tenants/get-the-caller-s-tenant): The tenant is resolved from the credential; there is no id to pass. `orgSettings` is its tenant-wide rule settings, `{}` when none were written.
### Through ovok
- **Who can call it:** Manager apps, and users whose access policy grants the capabilities.
- **Capabilities, all required:** `signals_config:read`. Project admins have every capability; client applications get no admin bypass.
- [Update tenant settings](/api/signals-api---tenants/update-tenant-settings): `settings` is merged, so a switch left out is left alone. Takes effect on the next request — except `throttleLimit`, which each replica caches for up to a minute.
`episodicAlerts` gates episode recording and the notification feed. `synchronousMode` makes ingest return before evaluating. `throttleLimit` overrides THROTTLE_LIMIT for this tenant; `0` exempts it.
`informationalCodes`, `historyCategories` and `feedCodes` (lists of strings, none by default): the codes the tenant's triggers consume and never judge (no no-verdict, and the `*` trigger skips them), the reading categories stored and never judged, and the codes the notification feed lists by default (none: every code). A new tenant is given the default pack's lists, and a tenant that states no `historyCategories` keeps the default pack's.
`ruleSet` is deprecated and ignored: readings are judged by the triggers in the rule settings, the tenant's (`orgSettings`) and each patient's own (`/api/patient/{id}/settings`).
`orgSettings` is the tenant's rule settings, which replace `/api/settings/org`: what the triggers judge by, the triggers themselves included. It is merged key by key: a key sent replaces the stored one whole, `null` removes it, and a key left out is kept. Its first write is given the default pack when it sends no `triggers`. Audited as `UPDATE_ORG_SETTINGS`. A band it changes ends the episodes judged under the old one, and a code it switches off (its band `"NO_THRESHOLD"`, or out of bed `enabled: false`) has its active alerts resolved and its open episodes closed `THRESHOLD_CHANGED` at the save, for every patient judged by the tenant's settings (an acknowledged out-of-bed absence, whose episode the ack closed, has its still-active alert resolved); a band deleted closes nothing. A tenant whose only org settings are one project's, with no patient stamped with another project, has them made the tenant's first, so the write reaches the patients they served.
`resolvedAt` (ISO 8601) is when the caller resolved `orgSettings`: it lands only over a write resolved earlier, or stored without one, and is otherwise refused 409 `STALE_SETTINGS` with nothing written. With `ifAbsent=true` each key of `orgSettings` is written only where the stored settings lack it, so a default seeded at enrolment cannot overwrite a concurrent save.
### 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.
- Only `orgSettings`, `resolvedAt` and `settings.episodicAlerts` are written through ovok. Turning `episodicAlerts` off stops Signals recording episodes, which empties episode feeds.
- 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.
- Sleepiz
- [Backfill missed Sleepiz nights](/api/sleepiz/backfill-missed-sleepiz-nights): Refills Sleepiz nights that the live push never delivered. Ovok pulls each night from the Sleepiz public API for one device and sends it through the same ingest path as live data.
**Auth:** Bearer token. The caller must be a project admin.
**Scope:** The caller's project (from the token) and its sub-projects. The device must belong to one of them. The route takes no project parameter.
## Behaviour
- The body is strict: `serialNumber` (6 to 10 digits), `from` and `to` (`YYYY-MM-DD`). Unknown fields are rejected.
- `from` to `to` is inclusive, `from` must not be after `to`, `to` must be yesterday (UTC) or earlier, and the range is at most 7 nights. Longer gaps need several calls.
- The device is looked up by its serial. It must be a Sleepiz serial, must belong to your project or one of its sub-projects (403 otherwise), and must have an assigned resident (409 otherwise). Assign the resident and call again. A serial held by devices in more than one project is refused with 409 too: ingest routes its readings to none of them.
- Nights are matched to the device's patient deployments in Sleepiz. Each night in the response has an `outcome`: `posted`, `no_recording`, `no_deployment` or `error`. One night failing does not stop the others.
- **`posted` means queued, not stored.** Ovok queues the night's Observations through the live ingest router and nothing is written to Medplum during the request. `jobIds` lists the queued jobs and `missingBlocks` names data Sleepiz had no samples for.
- Re-running the same device and range is safe. The queue job ids are deterministic and the Observation write is conditional on its event id, so no duplicates appear.
- The route answers 503 when the Sleepiz credentials are not configured on the server, and 502 when the Sleepiz API cannot be reached.
- **Last night needs no call.** Every day at 11:00 UTC ovok runs the same refill for yesterday's night on every device that has a resident and no recording of that night yet, except the stakeholder beds. Use this route for older nights.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/sleepiz/backfill' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "serialNumber": "", "from": "2026-01-01", "to": "2026-01-03" }'
```
- Slim
- Slim/Change History
- [List change history](/api/slim/change-history/list-change-history): Lists the recorded changes to thresholds, locations, zones, devices, residents, and users and their roles in your project, newest first. Use it for the resident and administration change-history screens.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Provenance:read`. Only the Admin and System Owner access policies carry it, so other users get no change history.
**Scope:** the caller's project (from the token). The rows are read with your token, so you only see changes recorded in your project.
## Behaviour
- Each row is one recorded change. `details.key` names the change and `details.values` holds the values to put into its message.
- Rows are sorted by recording time, newest first. `sort=asc` returns the same rows oldest first. Rows recorded in the same millisecond keep one fixed order, so paging never skips or repeats a row.
- Without `startDate`, the list starts 30 days before now. `endDate` is optional. Both bounds are inclusive.
- `types` limits the rows to the given change types. Omit it to get every type. Repeat the parameter to pass several types.
- `scope=global` keeps only project-wide changes: organization threshold edits, device, location and zone lifecycle changes, and user and role changes. `scope=all` (the default) returns every row.
- `types=Access` lists the user and role changes: a user invited (`userInvited`), renamed (`userRenamed`), moved to another role (`userRoleChanged`) or removed (`userRemoved`), and a role created (`roleCreated`), given other permissions (`rolePermissionsChanged`) or deleted (`roleDeleted`). They name users and roles by name and concern no resident.
- `userId`, `residentId`, `deviceId`, `locationId` and `zoneId` are ids, not references. Each takes several ids, repeated or comma-separated, and matches a row concerning any of them. Different filters combine with AND. `userId` matches the practitioner who made the change. A value that is not an id answers 422.
- `relatedTo` takes typed references (`Patient/`, `Device/`, `Location/`, `Organization/`), repeated or comma-separated, and returns every row concerning any of them, once each.
- `actions` keeps the kinds of change you name: `created`, `deleted`, `renamed`, `moved`, `assigned`, `unassigned`, `discharged`, `reactivated`, `thresholdChanged`. Rows recorded before this filter shipped carry no kind, so they never match it.
- `resident` on a row is the resident it concerns, `{patientId, residentId}`, or null when it concerns none. `residentId` inside it is their Resident ID, or null when they have none: show a placeholder, never a name. The flat `residentId` carries the same Resident ID, or is empty. Neither is ever a name or an internal id.
- Threshold and Signals settings changes made through the Signals API are listed as Threshold changes, with the reason given.
- Changes a device makes itself, such as a baseline re-push after a new 7-day mean, are never listed, and never counted in `total`.
- Unknown query parameters are ignored.
- `page` is zero-based and `count` defaults to 50, maximum 100. `total` counts only rows the list can return, and never exceeds 10,000. Pages from offset 10,000 on come back empty, so narrow the filters or the date range to reach older rows.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/change-history?types=Threshold&types=Resident&page=0&count=50' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/Device
- [List projects for device assignment](/api/slim/device/list-projects-for-device-assignment): Lists the projects you can move a device into: your own project, its parent project and its sub-projects.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:update`.
**Scope:** the caller's project (from the token) and its parent and sub-projects.
## Behaviour
- Each entry is `{ project: { id, name } }`. `name` is an empty string when the project has none.
- `total` is the number of projects returned.
- Read-only.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/assign/project' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Move device to another project](/api/slim/device/move-device-to-another-project): Moves a device into another project in your project tree, and optionally places it in a location there.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:update`.
**Scope:** the device must be in the caller's project or one of its sub-projects. The target `projectId` must be your project, its parent or one of its sub-projects.
## Behaviour
- The device's resident, location and zone are removed before the move, because those references belong to the old project.
- If a resident was assigned, their active out-of-bed episode is closed and their open device use record is ended, in the same write.
- When you send `locationId`, the device is placed in that location. The location must be in the target project.
- The move is written in one transaction. If it fails, nothing is written.
- Moving a device to the project it is already in writes nothing and still succeeds.
- The response is `{ success, deviceId, projectId, locationId }`. `locationId` is `null` when you sent none.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/device/assign/project' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{"deviceId": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "projectId": "87ea5dfc-8b8e-384d-8489-79496e706390"}'
```
- [List devices](/api/slim/device/list-devices): Lists the devices in your project with their zone, location and resident names. Use it for device directory and administration screens.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:search` and `Device:read`.
**Scope:** the caller's project (from the token).
## Behaviour
- Every device in the project is listed, whether or not it has a location or resident.
- `id` is the Device resource id. `thingsboardId` is the device identifier that telemetry is keyed by.
- `status` is `active` when the device's live telemetry reports it active, otherwise `inactive`.
- `lastActivityTime` is the latest telemetry activity time, or the device's last-seen time when telemetry has none.
- `search` matches device, location and zone names. `patientSearch` matches resident names. Both are case-insensitive substring matches.
- `organizationId`, `locationId`, `patientId` and `active` filter on exact values.
- `orderBy` is `ASC` or `DESC` in any case, default `ASC`. Rows with an empty sort value sort last in `ASC` order and first in `DESC` order.
- `page` is zero-based. `count` defaults to 20, maximum 100. `total` is the number of rows after filtering.
- The device structure is cached for up to 5 minutes. Writes made through the Slim routes refresh it sooner.
- If the device list cannot be built and no earlier complete list exists, the route returns 503. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device?page=0&count=20&sortBy=deviceName&orderBy=ASC' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create device](/api/slim/device/create-device): Creates a device in your project and, optionally, assigns it to a zone, a location and a resident in the same write.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:create`.
**Scope:** the device is created in the caller's project (from the token).
## Behaviour
- `name` is stored, trimmed, as the device's user-friendly name and as its official device identifier.
- A `name` whose serial a device of your project already holds is refused with 422, in any spelling: spaces around it or its `/`, other case, with or without the manufacturer prefix ingest gives the serial (`Sleepiz/30QD24001`, `sleepiz/30qd24001` and `30QD24001` hold one serial). Ingest finds a device by its serial, so one serial belongs to one device.
- A `name` whose serial a device of another customer already holds is refused with 409, in the same spellings. Ingest routes readings by serial, and cannot tell two customers' devices with one serial apart.
- `thingsboardId` is stored as a second identifier. When you omit it, Ovok generates a random UUID for it.
- `organizationId`, `locationId` and `patientId` are optional. Each one you send is assigned in the same transaction as the create. If any part fails, nothing is written.
- A device in a room is in the room's zone. An `organizationId` that differs from the zone of the device's room (the room you send, or the one it is in) answers 422 with `path: ["organizationId"]` and changes nothing: move the room to that zone, or the device to a room in it. A device with no room, or in a room with no zone, takes any zone. A zone change re-zones only the device, never its room, the room's other devices or a resident.
- Assigning a resident moves them: the resident is removed from every other device they hold, and their active out-of-bed episode is closed.
- Assigning a resident who is not active (`discharged`, `discharged-recent` or `archived`) is refused with 422 and nothing is created: reactivate them first.
- The device starts with status `active`.
- The create is recorded in the change history.
- The response is the same as `GET /v1/slim/device/{id}` for the new device.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/device' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{"name": "Sleepiz/3001000", "locationId": "c3499c27-2973-0a7f-807e-fb8676a92dcb"}'
```
- [List live device rows](/api/slim/device/list-live-device-rows): Lists live device rows for the dashboard's monitoring views: each device with its resident, location, zone, current telemetry and alerts.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token).
## Behaviour
- By default only devices with a resident assigned are returned. Set `includeUnassigned=true` to include devices without a resident.
- `organizationId` takes a zone id, `assigned` or `unassigned`. A zone id also matches devices in its child zones.
- `deviceId` restricts the result to one device, matched against the device identifier.
- `effectiveSleepStatus` filters on the device's current sleep status.
- `search` matches resident nickname and name, location name, zone name, and device name, identifier and serial. The resident, location and zone names match fuzzily; the device fields match only as a case-insensitive substring, so a full device name finds that device alone.
- `orderBy` is `ASC` or `DESC` in any case, default `ASC`.
- `residentState` is accepted but ignored.
- A row's `patient` carries the resident's `id`, `name`, `meta` and `extension` only, not the whole FHIR Patient.
- Telemetry is read fresh on every request. The device structure is cached and refreshed when you write through the Slim routes.
- `page` is zero-based. `count` defaults to 20, maximum 100.
- For polling only the telemetry and alerts, use `GET /v1/slim/device/live/telemetry` with the same query.
- The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/live?page=0&count=20&sortBy=locationName&orderBy=ASC' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List live telemetry and alerts by device](/api/slim/device/list-live-telemetry-and-alerts-by-device): Returns the telemetry and alerts for one page of live devices, keyed by device. Use it to poll the values on a page you already loaded with `GET /v1/slim/device/live`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token).
## Behaviour
- Takes the same query parameters as `GET /v1/slim/device/live` and selects the same page of devices in the same order.
- `telemetry` and `alerts` are keyed by the device identifier (for example `Sleepiz/3001000`), not by the Device resource id.
- `alerts` has an entry for every device on the page. `telemetry` has an entry only for devices with telemetry.
- Each telemetry entry carries the room readings `roomTemperature` (°C), `humidity` (%), `soundLevel` (dB), `infrared`, `illuminance` (lux), `airQualityIndex`, `tvoc` (ppb) and `eco2` (ppm) as `{ value, ts }`. They are `null` until the device reports one, and again when it has sent none for 30 minutes. They do not depend on whether the resident is in bed.
- `total`, `page` and `count` describe the page, as on `/live`.
- Telemetry is read fresh on every request.
- The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/live/telemetry?page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List live device rows (lean)](/api/slim/device/list-live-device-rows-lean): Lists live device rows for the dashboard's monitoring views, with only the fields the dashboard renders: each device with its resident, room, zone, current readings and alert colours.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token) and its sub-projects.
## Behaviour
- The same query, filters, search, sort and paging as `GET /v1/slim/device/live`. The difference is where the rows come from: only the Devices are read, with the resident, room and zone context every Slim write stores on them, instead of a sweep of every Patient, Location and Organization of the project.
- Every field is present; an absent value is `null`.
- The resident, room and zone values are the copies stored on the Device, so what a row shows follows the Device's project and access, not a fresh read of the Patient. Each backend fills in devices no Slim write has touched once per build, after it boots; until then such a device answers `residentState: null` and no zone.
- `id` is the Medplum Device id. `GET /v2/slim/device/live/telemetry` keys its readings by it.
- The device structure is cached and refreshed when you write through the Slim routes. Readings and alerts are read fresh on every request.
- `page` is zero-based. `count` defaults to 20, maximum 100.
- The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v2/slim/device/live?page=0&count=20&sortBy=locationName&orderBy=ASC' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List live telemetry and alerts by device (lean)](/api/slim/device/list-live-telemetry-and-alerts-by-device-lean): Lists the current readings and alert colours of one page of live devices, keyed by Medplum Device id. Poll it with the query you sent to `GET /v2/slim/device/live` to refresh the vitals without reloading the rows.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token) and its sub-projects.
## Behaviour
- Takes the same query as `GET /v2/slim/device/live` and answers for the same page of devices.
- `resources` maps each Device id to its `telemetry` (`null` when the device has sent nothing recent) and `alerts`.
- Readings and alerts are read fresh on every request.
- The route returns 503 when the server is at capacity for live reads. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v2/slim/device/live/telemetry?page=0&count=20&sortBy=locationName&orderBy=ASC' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Resolve how ingest routes device serials](/api/slim/device/resolve-how-ingest-routes-device-serials): For each serial you send, returns the manufacturer and model that ingest files it under, and whether ingest accepts the serial at all. Use it to check serials before you create devices or send data.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read`.
## Behaviour
- Send 1 to 500 serials, each at most 64 characters.
- Rows come back in the order you sent them.
- `routable: false` means ingest rejects the serial with `400`. `manufacturer` and `model` are then `null`.
- The serial alone decides the result. A manufacturer that ingest only accepts when named explicitly, such as Masimo, is never inferred from a serial.
- Nothing is read or written. The result is computed from the serial only.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/device/routing' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{"serials": ["3001000", "12,34"]}'
```
```json
{
"resources": [
{ "serial": "3001000", "manufacturer": "Sleepiz", "model": "OnePlus", "routable": true },
{ "serial": "12,34", "manufacturer": null, "model": null, "routable": false }
]
}
```
- [Get device](/api/slim/device/get-device): Returns one device with its zone, location and resident assignments and its current connection status. Use it to show or edit a single device.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read`.
**Scope:** the device is read with your token, so Medplum's access policy limits which devices you can read.
## Behaviour
- `organizationId` is the zone of the device's location. When the device has no location, it falls back to the device's own owner organization.
- `organizationName`, `locationName` and `patientName` are display names. Each is `null` when the resource has no name that can be shown.
- `status` is `active` only when the device was last seen recently enough. A device whose last-seen time is stale reads `inactive`, even if it was never marked offline. A device without an identifier reports its stored FHIR status.
- `statusReason` explains an `inactive` status when the platform recorded why.
- `floor`, `room` and `bed` come from the address of the device's location.
- Read-only. Nothing is written.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Delete device](/api/slim/device/delete-device): Deletes a device from your project.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:delete`. System Owners cannot delete devices.
**Scope:** the device must belong to the caller's project (from the token).
## Behaviour
- The Device resource is deleted. This cannot be undone.
- If a resident is assigned, they are unassigned and their active out-of-bed episode is closed in the same transaction.
- The device's use history is updated in the same transaction.
- The delete is recorded in the change history.
- The response has no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/device/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update device](/api/slim/device/update-device): Updates a device's name and identifier, and assigns or unassigns its zone, location and resident.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:update`.
**Scope:** the device must belong to the caller's project (from the token).
## Behaviour
- `name` is required and replaces the device's user-friendly name, trimmed. Renaming the device to a serial that a device of another customer already holds is refused with 409, in any spelling.
- Renaming the device to a serial another device of your project holds is refused with 422, in any spelling: spaces around it or its `/`, other case, with or without the manufacturer prefix ingest gives the serial. A device may take another spelling of its own serial.
- For `organizationId`, `locationId` and `patientId`: omit the field to leave it unchanged, send `null` to unassign, or send a UUID to assign.
- A device in a room is in the room's zone. An `organizationId` that differs from the zone of the device's room (the room you send, or the one it is in) answers 422 with `path: ["organizationId"]` and changes nothing: move the room to that zone, or the device to a room in it. A device with no room, or in a room with no zone, takes any zone. A zone change re-zones only the device, never its room, the room's other devices or a resident.
- Assigning a resident moves them: the resident is removed from every other device they hold. The resident who was on this device before loses it. Each resident who loses a device has their active out-of-bed episode closed in the same transaction.
- Assigning a resident who is not active (`discharged`, `discharged-recent` or `archived`) is refused with 422 and changes nothing: reactivate them first. Unassigning one (`patientId: null`) is allowed.
- All changes are written in one transaction. If any part fails, nothing is written.
- Sending values the device already has is not an error, and writes nothing.
- Resident assignment changes, renames, identifier changes and zone changes are recorded in the change history.
- The response is the same as `GET /v1/slim/device/{id}` after the update.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/device/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{"name": "Sleepiz/3001000", "patientId": null}'
```
- Slim/Export
- [Create night report PDF](/api/slim/export/create-night-report-pdf): Creates a night report PDF for one resident and stores it. Optionally emails the PDF. Use it for the report download and email feature on the dashboard.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device` and `Observation`.
**Scope:** the caller's project (from the token). The resident is read with your token, so Medplum's access policy limits which residents you can export.
## Behaviour
- `code` must be `TRENDS_PDF_EXPORT`. Any other value is rejected with `400`.
- The report layout comes from the export template content for `code` and `language`. A template in your project wins over one in its parent project. The route returns `400` when no template exists.
- The report period is `(period.start, period.end]` in the project's time zone: for a range of more than one day the first day is left out, because its night belongs to the day before. A single-day range reports that day. A night counts for the day its sleep ends.
- The report covers sleep statistics, heart rate and respiratory rate for each night. It holds only what ends inside one of the resident's use periods of its device, as `GET /v1/slim/sleep/statistics` does: the sleep table's recordings, and the readings behind the heart and respiratory rate rows and charts. A reading with no end time is then left out. So a previous resident's night that ended before the device was handed over, but reached Ovok after it, is not reported. A resident with no device use history has everything reported.
- When a night has several sleep recordings left, the sleep table uses the one written last (latest `meta.lastUpdated`), the rule `GET /v1/slim/sleep/statistics` uses.
- Once a resident has any use period, the report also leaves out what a device with no period of theirs recorded, and what a device recorded before its earliest period. A device assigned before use periods were recorded gets its first one on its next edit in Ovok, starting at the Device's last write before that edit, so what it recorded before then is not reported. Each device whose readings in a report all drop is counted in the `sleep.device_use_device_dropped` metric and logged at most once a minute.
- Report times use the project's time zone. The `timeZone` field in the body is not used.
- The PDF is stored as a Binary, and a `DocumentReference` links it to the resident. Both are written in one transaction, so a failed store leaves neither. The response is that `DocumentReference`. Its `content[0].attachment.url` points to the Binary.
- When `mailTo` has addresses, the PDF is emailed to them as an attachment after the store succeeds. The email is sent in the language you set. With no addresses, nothing is emailed.
- If the email cannot be sent, the route returns `500`, but the report has already been stored.
- Every call creates a new report. Nothing is deduplicated.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/export/pdf' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"code": "TRENDS_PDF_EXPORT",
"patientId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"language": "en",
"period": { "start": "2026-09-21T00:00:00Z", "end": "2026-09-28T00:00:00Z" },
"mailTo": ["max.mustermann@example.com"]
}'
```
- Slim/Health
- [Get health status](/api/slim/health/get-health-status): Returns the health of the Slim API and the systems it depends on. Use it for uptime checks and status screens.
**Auth:** none.
## Behaviour
- `status` is `healthy` when both the FHIR store and Redis are up, `degraded` when one is down, and `unhealthy` when both are down. The route still answers `200` in every case, so read `status`, not the HTTP code.
- `externalSystems.fhirStore` and `externalSystems.redis` hold each system's own status and, when available, its version, memory and connection figures. `responseTimeMs` is the time the FHIR store took to answer its health check.
- `cache` holds hit, miss and error counts of the application cache since the process started.
- `ovok`, `system` and the FHIR store `serverMetrics` come from the monitoring system, from the last 5 minutes. They are left out when monitoring is not configured or does not answer.
- `uptimeSeconds` is the time since this process started. `version` is `null` when the deployment does not set one.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/health'
```
- Slim/Invite
- [Invite practitioner](/api/slim/invite/invite-practitioner): Invites a practitioner to your project, or to one of its direct child projects, and emails them a link to set their password.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:create` (a project admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token), or `projectId` when given. `projectId` must be the caller's project or a direct child of it.
## Behaviour
- Practitioner invitations must be enabled on the target project. They are enabled unless the project turns them off.
- `accessPolicyId` must name a policy of your project, its parent or a direct child, at or below your own rank. It is checked before anything is written.
- An existing practitioner account with this `email` in the target project is refused: an invite never changes a member's role or admin flag (use `PUT /v1/slim/policy/{id}`). An existing practitioner account elsewhere, your own project included, is reused: only the membership and practitioner profile are new. A patient account of another project is not: it is that project's own, and the invitee gets a practitioner account of their own.
- Ovok creates the membership with the access policy and the practitioner profile, then emails an invitation with a password-setup link. The link points to the app the request came from, and sets a password for 7 days after it was sent. If the email fails, the account is undone and the request answers 400.
- `admin` in the body is ignored. The invitee becomes an admin member, and the project owner, only when the target project has no owner yet.
- The invitee shows as `Pending` in user lists until they set a password.
- Returns the new membership, the practitioner profile and `status: "Pending"`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/invite/practitioner' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"email": "max.mustermann@example.com",
"name": "Max",
"surname": "Mustermann",
"accessPolicyId": "c3499c27-2973-0a7f-807e-fb8676a92dcb"
}'
```
- Slim/Location
- [List location assignment candidates](/api/slim/location/list-location-assignment-candidates): Lists locations a resident can be placed in, flagged as occupied or vacant. Use it to fill the location picker when you assign a resident.
**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 `Location:search`, `Location:read`, `Device:read`, `Patient:read` and `Organization:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). A non-admin token without a project is refused.
## Behaviour
- Read-only.
- Built from the same data as `GET /v1/slim/location`: **one row per device** at a location, and one row for a location with no device. `total` counts rows.
- `occupied` is `true` when the row's device has a resident assigned. Such rows carry `warningCode: "location_has_existing_resident"`. Otherwise `warningCode` is `null`.
- `assignable` is always `true`.
- Fields with no value are `null`.
- `search` and `organizationId` filter as on `GET /v1/slim/location`. `occupied` takes `occupied`, `vacant` or `all` (default `all`).
- Rows are sorted as on `GET /v1/slim/location`.
- Pagination is zero-based: `page` (default `0`) and `count` (default `50`, max `50`).
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location/assignment-candidates?occupied=vacant&count=50' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{
"total": 1,
"page": 0,
"count": 50,
"resources": [
{
"locationId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"locationName": "Room 201 Bed 1",
"organizationId": null,
"organizationName": null,
"deviceId": null,
"deviceName": null,
"patientId": null,
"patientName": null,
"occupied": false,
"assignable": true,
"warningCode": null
}
]
}
```
- [List locations](/api/slim/location/list-locations): Lists the locations (rooms and beds) in your project, with the device, resident and zone at each one. Use it for the location table in the Slim dashboard.
**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 `Location:search` and `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). Only locations, devices and residents in that project are returned.
## Behaviour
- Read-only.
- **One row per device.** A location with several devices appears once per device. A location with no device appears once, without device and resident fields. `total` counts rows, not locations.
- `patientId` and `patientName` are the resident assigned to that row's device. `organizationId` and `organizationName` are the location's zone.
- `search` matches, as a case-insensitive substring, the location name, the name of a device at the location, the name of a resident on such a device, or the zone name.
- `floor`, `room` and `bed` match the location's codes exactly. `organizationId` keeps locations in that zone. `deviceId` keeps only the row for that device.
- Rows are sorted by floor, room, bed, device name, then location name. The sort is case-insensitive and numeric-aware ("2" before "10"). Rows with a missing value sort after rows that have one.
- Pagination is zero-based: `page` (default `0`) and `count` (default `20`, max `100`).
- Unknown query parameters are rejected.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location?search=Room%20201&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create location](/api/slim/location/create-location): Creates a location (room or bed), optionally in a zone.
**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 `Location:create` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The location is created in the caller's project (from the token). A super-admin caller can pass `?projectId=` to create it in that project instead. Any other caller who passes `projectId` gets a 403.
## Behaviour
- `name` must be unique. The check is an exact name match against the locations your token can search. With `?projectId`, the check runs in that project only.
- When any of `floor`, `room` or `bed` is set, the combination of zone, floor, room and bed must also be unique. The comparison ignores case and extra whitespace. A location with only a name has no such check.
- `floor`, `room` and `bed` are stored as type codes on the location. `organizationId` sets the zone. The zone must be in your project, one of its sub-projects, or its parent project.
- The create is guarded against a concurrent create of the same floor, room and bed. If another request creates it first, you get a 409 that names the existing location.
- No devices or residents are attached. Use `PUT /v1/slim/location/{id}` for that.
- A location-created entry is added to the change history. A failure to write that entry does not fail the request.
- The response is the created location, in the same shape as `GET /v1/slim/location/{id}`.
- If a location with the same zone, floor, room and bed exists, the request is refused with 409 and the body carries `existingLocationId` and `existingLocationName`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/location' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390"
}'
```
- [List locations in a project (admin)](/api/slim/location/list-locations-in-a-project-admin): Lists the locations of a given project. The admin dashboard uses it to fill the location picker after you choose a project.
**Auth:** Bearer token. The caller must be a Medplum project admin. Super admins without the admin role, practitioners and System Owner callers are refused. The access-policy check (`Location:search`, `Location:read`) is skipped only for an admin who holds no access policy.
**Scope:** The project named by the required `projectId` query parameter. The search runs with Ovok's admin client, not the caller's token.
## Behaviour
- Read-only.
- Locations are sorted by name.
- Pagination is zero-based: `page` (default `0`) and `count` (default `50`, max `100`).
- `total` is an estimate: when a page is full it is one more than the rows seen so far, so a full page means more may follow.
- Unlike `GET /v1/slim/location`, rows carry no device or resident fields: one row per location.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location/admin/list?projectId=c3499c27-2973-0a7f-807e-fb8676a92dcb&page=0&count=50' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create location in a project (admin)](/api/slim/location/create-location-in-a-project-admin): Creates a location in a given project. The admin dashboard uses it during device assignment, when the right room does not exist yet.
**Auth:** Bearer token. The caller must be a Medplum project admin. Super admins without the admin role, practitioners and System Owner callers are refused. The access-policy check (`Location:create`) is skipped only for an admin who holds no access policy.
**Scope:** The project named by `projectId` in the body. The location is created with Ovok's admin client and stamped with that project.
## Behaviour
- `floor`, `room` and `bed` are stored as type codes. `organizationId` sets the zone (`managingOrganization`).
- The location is created with `status: active`.
- Unlike `POST /v1/slim/location`, this route does not check for a duplicate name or a duplicate floor, room and bed, and adds no change-history entry.
- The response is `{ id, name, projectId }` of the created location.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/location/admin' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"projectId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"name": "Room 18",
"floor": "2",
"room": "18",
"organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390"
}'
```
- [Get location](/api/slim/location/get-location): Returns one location (room or bed) by id, with its zone, devices and resident.
**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 `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The location is read with the caller's own token, so you get any location your Medplum access lets you read. There is no extra project check on this route.
## Behaviour
- Read-only.
- `floor`, `room` and `bed` come from the location's type codes.
- `organizationId` and `organizationName` are the location's zone (`Location.managingOrganization`).
- `deviceId` lists every device at the location. `deviceName` is the alphabetically first of their names.
- `patientId` and `patientName` are the resident on the first device at the location that has one.
- Fields with no value are omitted.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{
"id": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390",
"organizationName": "Ward A",
"deviceId": ["..."],
"deviceName": "...",
"patientId": "...",
"patientName": "Maxi"
}
```
- [Delete location](/api/slim/location/delete-location): Deletes a location that has no devices attached.
**Auth:** Bearer token. The caller must be a Medplum project admin or super admin. The access policy must grant `Location:delete` and `Device:update` (an admin or super admin who holds no access policy skips the access-policy check).
**Scope:** The location must belong to the caller's project (from the token).
## Behaviour
- Detach every device first (`PUT /v1/slim/location/{id}` with `"deviceId": []`). A location with a device attached is refused.
- The Location resource is deleted.
- The write is atomic and takes a short write lock. A concurrent write to the same location gets a 409.
- A location-deleted entry is added to the change history. A failure to write that entry does not fail the request.
- The response has no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/location/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update location](/api/slim/location/update-location): Updates a location: its name, floor, room, bed and zone, the devices at it, and the resident on those devices.
**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 `Location:update` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The location must belong to the caller's project (from the token). Devices and residents you attach must be in your project or one of its sub-projects. The zone must be in your project, a sub-project, or the parent project.
## Behaviour
- `name` is required and must be unique among the locations your token can search, not counting this one.
- `floor`, `room`, `bed`: an omitted field keeps its current value. If the zone, floor, room or bed changes, the new combination must not match another location's.
- `organizationId`:
- omitted: the zone is unchanged.
- `null`: the zone is removed from the location and from every device at it.
- an id: the location and every device at it move to that zone. Residents on those devices move too.
- `deviceId` (one id or a list):
- omitted: the devices at the location are unchanged.
- a list: it becomes the full set of devices at the location. Devices not in the list are detached; new ones are attached. `null` or `[]` detaches all devices.
- Devices that hold a discharged resident cannot be attached.
- `patientId`:
- an id: that resident is assigned to the devices in `deviceId`, or, when `deviceId` is omitted or empty, to the single device at the location. The resident is first removed from any other device. A resident already on a target device is replaced. A discharged resident is refused.
- **omitted: every resident is removed from every device at the location and every device in `deviceId`.** To keep the current resident, send their `patientId`.
- A resident who loses a device has their active out-of-bed notification revoked in the same write, and the device's live telemetry state is cleared afterwards.
- Device use history is updated for every device whose resident changes.
- The write is atomic and takes a short write lock. A concurrent write to the same resources, or a device reassigned by someone else while this request ran, gets a 409.
- Every save adds a location-updated entry to the change history. Residents who move into a new zone, or lose a device, also get an entry in their own change history.
- The response is the location after the update, in the same shape as `GET /v1/slim/location/{id}`.
- If another location has the same zone, floor, room and bed, the request is refused with 409 and the body carries `existingLocationId` and `existingLocationName`.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/location/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390",
"deviceId": ["c3499c27-2973-0a7f-807e-fb8676a92dcb"],
"patientId": "c3499c27-2973-0a7f-807e-fb8676a92dcb"
}'
```
- Slim/Notifications
- [List recent notifications](/api/slim/notifications/list-recent-notifications): Lists the newest active notifications stored as CommunicationRequests for your project, of every type (such as out-of-bed, device alarms and attention presses). Use it for a notification bell. For filtered or paged history, use the out-of-bed and alarm feeds.
**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 `CommunicationRequest:read` and `CommunicationRequest:search` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Returns at most `count` rows (1 to 50, default 20), newest first by event time.
- Rows come from a Redis copy of the active notifications when that copy is enabled and loaded, and from a FHIR store search otherwise. `warm` is `true` and `source` is `redis` for the first case; `warm` is `false` and `source` is `fhirStore` for the second. A cold read also starts loading the Redis copy in the background, so a later call can be warm.
- The Medplum search returns `active` notifications updated within the last year.
- `total` counts the active notifications the source knows about, capped at the list result cap (1,000 by default). From Medplum it is an estimate.
- `locationName` is the room's current name, read from the Location as on the notification lists, so a renamed room shows its new name on every row, old alerts and new. When rows come from Redis, that lookup is cached per caller for up to a minute and dropped when a room is renamed through this API. If the caller cannot read the Location, or the lookup takes more than 2 seconds, a row keeps the name it was raised with.
- Rows whose notification type cannot be resolved are left out.
- Medical notifications (heart rate, respiratory rate and other vitals) are decided by Signals and served by `GET /v1/slim/notifications/recent/medical`. To show one type only, use `GET /v1/slim/notifications/recent/oob` or `GET /v1/slim/notifications/recent/alarms`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent?count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List recent medical notifications](/api/slim/notifications/list-recent-medical-notifications): Lists the newest open, unacknowledged medical notifications for your project. Use it for a medical notification bell. Medical episodes are decided by Signals; Ovok reads them from Signals and adds the resident context.
**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 `Patient:read`, `Device:read` and `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token), applied on both sides: Signals filters on the resident's project stamp, and Ovok checks each resolved resident against your project.
## Behaviour
- The filter is fixed by the server: open, unacknowledged episodes, newest last notification first (`episode.lastFiringAt`, or `episode.openedAt` when that is null), at most `count` (1 to 50, default 20). Every row's `episode.status` is `OPEN`. An episode leaves the bell when it closes, whether or not anyone acknowledged it. Closed episodes stay in `GET /v1/slim/notifications/medical`, where they can still be acknowledged with `POST /v1/slim/notifications/medical/{episodeId}/ack`.
- An open episode is listed however many closed episodes fired after it.
- Rows have the same shape as `GET /v1/slim/notifications/medical`, including `episode.firedBand`.
- `nextCursor` is set when the page is full, so more open, unacknowledged episodes may exist. A bell can ignore it.
- A resident who cannot be resolved into your project is left out, so a page can hold fewer than `count` rows.
- A resident with no Signals project stamp matches no project and does not appear.
- When the project's Signals tenant has episodic alerts switched off, the list is empty.
- A 503 with `signals_unavailable` means Signals could not be reached, not that there are no notifications; retry after `retryAfterSec`.
- Out-of-bed is not here; read `GET /v1/slim/notifications/recent/oob`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent/medical?count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List recent out-of-bed notifications](/api/slim/notifications/list-recent-out-of-bed-notifications): Lists the newest active out-of-bed notifications for your project. Use it for an out-of-bed notification bell.
**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 `CommunicationRequest:read` and `CommunicationRequest:search` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Out-of-bed alerts are episodes Signals decides (code `103214-3`); Ovok reads them from Signals and adds the resident context. Medical notifications are not here: read `GET /v1/slim/notifications/recent/medical` for those, so one event is never counted by both bells.
- Returns at most `count` rows (1 to 50, default 20): the newest unacknowledged episodes not closed by hand, by last firing, from the first 200 Signals holds for the last year.
- `deviceName` and `locationName` name the device the alert was raised on and its room's current name, also after the resident moved to another device or was unassigned.
- `total` counts every active row in those 200, capped at the list result cap (1,000 by default). `warm` is `true` and `source` is `signals`.
- An episode that has ended but has not been acknowledged stays active, and so stays in this bell, until someone acknowledges it with `PATCH /v1/slim/notifications/{id}/ack`.
- While Signals is unavailable, the bell answers the last page Signals gave it for your project, up to 10 minutes old and cut to `count`. An acknowledgement drops that page, so an acknowledged row never comes back. With no page kept, it answers 503 with `signals_unavailable`; retry after `retryAfterSec`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent/oob?count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List recent alarm notifications](/api/slim/notifications/list-recent-alarm-notifications): Lists the newest active device alarms and attention presses for your project. Use it for an alarm bell. It has the same response shape as `GET /v1/slim/notifications/recent/oob`.
**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 `CommunicationRequest:read` and `CommunicationRequest:search` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Device alarms and attention presses are decided by the sending system. Ovok stores and forwards them.
- Returns at most `count` rows (1 to 50, default 20), newest first by event time.
- Always read from the FHIR store, limited to the `deviceAlarm` and `attention` types, so `warm` is `false` and `source` is `fhirStore`.
- `total` counts alarm rows only. It is an estimate, capped at the list result cap (1,000 by default).
- Acknowledge a row with `PATCH /v1/slim/notifications/{id}/ack`; it then leaves this bell.
- Out-of-bed is on `GET /v1/slim/notifications/recent/oob`, medical notifications on `GET /v1/slim/notifications/recent/medical`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent/alarms?count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List out-of-bed notifications](/api/slim/notifications/list-out-of-bed-notifications): Lists your project's out-of-bed notifications, filtered and paged. Out-of-bed is evaluated and recorded by Ovok as CommunicationRequests, and this is its feed. Medical notifications are not here; read `GET /v1/slim/notifications/medical` for those.
**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 `CommunicationRequest:read`, `CommunicationRequest:search` and `Observation:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). The `project` query parameter is accepted but ignored.
## Behaviour
- The notification type is fixed to out-of-bed; there is no `type` parameter. Prefer this route over the deprecated `GET /v1/slim/notifications?type=outOfBed`.
- `status=active` lists the new notifications and `status=completed` the reviewed ones. Leave `status` out to list new and reviewed together; each row keeps its own `status`. An episode closed by hand without an acknowledgement is `revoked`, so it is in none of these lists; ask `status=revoked` for it. An episode that has ended but has not been acknowledged stays `active`, with an end-of-episode marker, so one resident can have more than one active row.
- One row per out-of-bed episode, not per reading: the resident's open episode is updated in place.
- Sort order: newest first by event time (`occurrenceDateTime`, then `authoredOn`, then id).
- `patient` takes a Patient id or `Patient/{id}`. `device` takes a Device id, `Device/{id}`, or the device's identifier value. A Device id that does not exist returns an empty page rather than an unfiltered one. `device` matches the device that raised each alert, and each row's device and room are that device's, also after the resident moved to another device or was unassigned.
- `startDate` and `endDate` are inclusive ISO 8601 UTC instants, used exactly as sent. They bind to the episode's last firing time (`occurrenceDateTime`), whatever the status. Either may be omitted. A missing `startDate` defaults to one year back for `status=active` and 30 days back otherwise. Without `status`, the new rows keep the one-year default and the reviewed rows the 30-day one, so the list holds exactly the rows of `status=active` and `status=completed` together.
- Paging: `page` from 0, `count` from 1 to 100 (default 25). `total` is an exact count for the filter, the same on every page, cached for 15 seconds. It counts matching CommunicationRequests, so it is an upper bound on the rows you can page through. It reads `0` if the count lookup fails; the rows are unaffected.
- The list pages through at most the first 1,000 results (server-configurable). `total` is clamped to that cap. When the cap or the per-request scan limit stops a page short, `truncated` says why: `{ reason: 'result-cap', limit }` or `{ reason: 'scan-budget', limit }`. `truncated` is `null` when the page is complete.
- Acknowledge a row with `PATCH /v1/slim/notifications/{id}/ack`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/oob?status=active&page=0&count=25' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List alarm notifications](/api/slim/notifications/list-alarm-notifications): Lists your project's device alarms and attention presses, filtered and paged. These are decided by the sending system; Ovok stores them as CommunicationRequests and forwards them.
**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 `CommunicationRequest:read`, `CommunicationRequest:search` and `Observation:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). The `project` query parameter is accepted but ignored.
## Behaviour
- One row per alarm episode. Each row's `alarm` carries the sender's own alarm id (`episodeId`), its severity, type and text, so the sender can match an acknowledgement to its own record.
- `type`: `deviceAlarm`, `attention`, or both comma separated. Both when omitted.
- `severity`: `RED`, `YELLOW`, `ATTENTION`, comma separated, as the sender coded the alarm. Every severity when omitted.
- `status` defaults to `active`; an acknowledged alarm is `completed`.
- `sort`: `newest` (default) or `oldest`, by event time (`occurrenceDateTime`, then `authoredOn`, then id).
- `patient`, `device`, `startDate`, `endDate`, `page`, `count`, `total` and `truncated` work as on `GET /v1/slim/notifications/oob`: `count` is 1 to 100 (default 25), dates are inclusive UTC instants, and the list pages through at most the first 1,000 results (server-configurable).
- Acknowledge a row with `PATCH /v1/slim/notifications/{id}/ack`.
- Out-of-bed is on `GET /v1/slim/notifications/oob`; vital-sign alerts, decided by Signals, are on `GET /v1/slim/notifications/medical`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/alarms?type=deviceAlarm&severity=RED&sort=newest' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List medical notifications](/api/slim/notifications/list-medical-notifications): Lists your project's medical notifications (heart rate, respiratory rate and other vital-sign alerts), newest last notification first, one page at a time. Medical episodes are decided by Signals; Ovok reads them from Signals, adds the resident context, and never re-derives a clinical value.
**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 `Patient:read`, `Device:read` and `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token), applied on both sides: Signals filters on the resident's project stamp, and Ovok checks each resolved resident against your project.
## Behaviour
- Order: newest last notification first. That is `episode.lastFiringAt`, the newest reading outside the band, or `episode.openedAt` for an episode stored without one (before 2026-09-28). An open episode that fires again moves up, so while you read page 2 it can move to page 1. It is never listed twice, and the next read of page 1 shows it.
- One row per episode, not per reading: a run of readings outside the band is one episode, which closes on recovery or acknowledgement.
- Each row has three blocks. `episode` is the Signals episode with its aggregates. `carehub` is the resident context Signals does not hold: resident, room and bed, device, zone. `patientName` is the resident's Resident ID, also after a discharge, an unassign or a device move. The room, bed, device and zone are those of the device the episode was raised on, also after the resident moved to another device or was unassigned. They are `null` when that device is not known or is no longer in your project. `acknowledgement` is `null` until someone acknowledges the episode.
- Use `episode.id` with `GET /v1/slim/notifications/medical/{episodeId}` to get the full value history.
- `episode.firedBand` is the band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from Signals' configuration history at the episode's trigger version. It is not the resident's current band, so editing a threshold does not change past rows. `min` and `max` are each nullable (a band can be one-sided). `firedBand` is `null` when the band cannot be established; that never fails the read.
- Filters: `status` (`OPEN` or `CLOSED`, both when omitted), `since` (episodes whose last notification, as in the order above, is at or after this ISO 8601 instant), `acknowledged` (`true`, `1` or `yes` for acknowledged only; any other value for unacknowledged only; both when omitted).
- `patient` narrows the feed to one resident, by Medplum `Patient.id` (the `carehub.patientId` a row returns). It does not change the project scope. A resident who cannot be resolved, or who is in another project, answers 404 rather than an unfiltered page.
- `codes` narrows the feed to these LOINC codes, comma separated, at most 32 (for example `8867-4,9279-1`). Perfusion index is `PI`. Signals applies the filter. Out-of-bed is never in this feed.
- Paging: `limit` is 1 to 200 (default 50). Pass the previous page's `nextCursor` as `cursor`. Page until `nextCursor` is `null`, not until a short page arrives: rows whose resident cannot be resolved into your project are dropped after Signals counted them.
- A resident with no Signals project stamp matches no project and does not appear.
- When the project's Signals tenant has episodic alerts switched off, the page is empty.
- Out-of-bed is served by `GET /v1/slim/notifications/oob`.
- A 503 with `signals_unavailable` means Signals could not be reached; retry after `retryAfterSec`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical?status=OPEN&codes=8867-4,9279-1&limit=50' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get medical notification](/api/slim/notifications/get-medical-notification): Returns one medical notification with its full value history, addressed by the `episode.id` a feed row carries. The episode is read from Signals, which decides medical alerts.
**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 `Patient:read`, `Device:read` and `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token), applied on both sides: Signals matches it against the resident's project stamp, and Ovok checks the resolved resident against your project.
## Behaviour
- `episode` is the Signals episode as Signals returned it: status, open and close times, close reason, aggregates, and every reading recorded while it ran (`values`). Check `episode.truncated`: a very long episode returns a capped series and says so.
- `carehub` adds the resident context: resident, room and bed, device and zone. `patientName` is the resident's Resident ID, also after a discharge, an unassign or a device move. The room, bed, device and zone are those of the device the episode was raised on, also after the resident moved to another device or was unassigned. They are `null` when that device is not known or is no longer in your project.
- `acknowledgement` is `null` until someone acknowledges the episode.
- `episode.firedBand` is the band the episode was judged under, as described on `GET /v1/slim/notifications/medical`. It is `null` when it cannot be established.
- An episode in another project, or an out-of-bed episode (code `103214-3`), answers 404, the same as one that does not exist. A 404 is never caused by Signals being down.
- A 503 with `signals_unavailable` means Signals could not be reached; retry after `retryAfterSec`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Acknowledge medical notification](/api/slim/notifications/acknowledge-medical-notification): Acknowledges one medical notification, so it leaves the medical bell. The acknowledgement is written to Signals, which owns medical episodes.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). Ovok reads the episode with your project and checks its resident against your project before it writes anything.
## Behaviour
- No CommunicationRequest is created or changed. Signals closes the episode with reason `ACKNOWLEDGED`. A resident still outside the band opens a new episode on their next reading.
- Repeating the call is safe.
- Answers 200 with the acknowledged row, in the feed's row shape, already carrying the new `acknowledgement` and closed status. Replace the list entry with it; no refetch is needed.
- `acknowledgement.acknowledgedBy` is Ovok's client id at Signals, not a person; do not show it as a name. `acknowledgement.acknowledgedActor` is the caller's profile reference and display name, or `null` when the session has no profile.
- Ovok clears its cached index of the project's open episodes, so other reads see the episode as closed straight away rather than after a cache expiry.
- An episode in another project, an out-of-bed episode (code `103214-3`) or one that does not exist answers the same 404, and nothing is acknowledged. Acknowledge an out-of-bed alert with `PATCH /v1/slim/notifications/{id}/ack`.
- A 409 means the project's Signals tenant has episodic alerts switched off.
- While Signals does not answer, Ovok keeps trying for up to 12 seconds before it answers. A 503 (`signals_unavailable`) means Ovok could not confirm the acknowledgement; repeat the call after `retryAfterSec` (also sent as `Retry-After`).
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/c3499c27-2973-0a7f-807e-fb8676a92dcb/ack' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Leave a note on a notification](/api/slim/notifications/leave-a-note-on-a-notification): Leaves a note on a notification. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check). Only a practitioner can write notes.
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- `kind` names the feed the notification comes from: `oob` or `alarm` with the row's `commId` as `id`, `medical` with the row's `episode.id`, or `alert` with a raw Signals alert's `id`.
- A note on a raw alert is also listed and counted on that alert's episode. Which episode is decided once, when the note is written.
- `text` is trimmed and must be 1 to 2000 characters.
- The author is the calling practitioner, never a body field.
- Notes can be left on acknowledged notifications too.
- `medical` and `alert` notes are read from Signals first, so they answer 503 `signals_unavailable` while Signals is down. Retry once Signals is back.
- Answers 201 with the note as stored.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/notes' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "kind": "oob", "id": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "text": "Resident was in the bathroom." }'
```
- [An out-of-bed notification's notes](/api/slim/notifications/an-out-of-bed-notification-s-notes): Lists the notes on an out-of-bed notification. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `CommunicationRequest:read` and `CommunicationRequest:search` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- `id` is the notification row's `commId`.
- Newest first. Deleted notes are not listed.
- Read-only.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/oob/c3499c27-2973-0a7f-807e-fb8676a92dcb/notes' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [An alarm notification's notes](/api/slim/notifications/an-alarm-notification-s-notes): Lists the notes on an alarm notification. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `CommunicationRequest:read` and `CommunicationRequest:search` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- `id` is the notification row's `commId`.
- Newest first. Deleted notes are not listed.
- Read-only.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/alarms/c3499c27-2973-0a7f-807e-fb8676a92dcb/notes' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [A medical notification's notes](/api/slim/notifications/a-medical-notification-s-notes): Lists the notes on a medical notification. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `Patient:read`, `Device:read` and `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- `episodeId` is the feed row's `episode.id`.
- Newest first. Deleted notes are not listed.
- The episode is read from Signals first, as the detail and the acknowledgement read it, so this answers 503 `signals_unavailable` while Signals is down.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/c3499c27-2973-0a7f-807e-fb8676a92dcb/notes' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [A raw Signals alert's notes](/api/slim/notifications/a-raw-signals-alert-s-notes): Lists the notes on a raw Signals alert. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The alert is read from Signals first: 404 when it isn't in the caller's project or the caller can't read its resident.
## Behaviour
- Newest first. Deleted notes are not listed.
- Answers 503 `signals_unavailable` while Signals is down. Retry once Signals is back.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/raw-alerts/c3499c27-2973-0a7f-807e-fb8676a92dcb/notes' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Edit a note's text](/api/slim/notifications/edit-a-note-s-text): Changes a note's text. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check). Only the note's author can change it.
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- Same effect as `PUT`: a note's text is the only field a caller can change.
- `text` is trimmed and must be 1 to 2000 characters.
- If the note changed while your edit was in flight, the route answers 409. Reload the note and try again.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/v1/slim/notifications/notes/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "text": "Resident was in the bathroom; back in bed 02:14." }'
```
- [Delete a note](/api/slim/notifications/delete-a-note): Deletes a note. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check). Only the note's author can delete it.
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- The note is marked `entered-in-error`, not erased, so the clinical record and its history survive.
- A deleted note leaves every list and every `noteCount`.
- Answers 204 with no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/notifications/notes/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Replace a note's text](/api/slim/notifications/replace-a-note-s-text): Changes a note's text. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check). Only the note's author can change it.
**Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
## Behaviour
- Same effect as `PATCH`: a note's text is the only field a caller can change.
- `text` is trimmed and must be 1 to 2000 characters.
- If the note changed while your edit was in flight, the route answers 409. Reload the note and try again.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/notifications/notes/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "text": "Resident was in the bathroom; back in bed 02:14." }'
```
- [Acknowledge notification](/api/slim/notifications/acknowledge-notification): Acknowledges one notification stored as a CommunicationRequest (out-of-bed, device alarm, attention press) by setting its status to `completed`. For a medical notification, use `POST /v1/slim/notifications/medical/{episodeId}/ack` instead.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check). No `CommunicationRequest:update` grant is needed.
**Scope:** The CommunicationRequest is read with your own credentials and must belong to your project (from the token). Sub-projects are not included.
## Behaviour
- After those checks pass, Ovok writes the status change with its own credentials.
- Acknowledging an already completed notification succeeds and changes nothing.
- If the notification is updated at the same moment (for example by a new reading on the same episode), Ovok re-reads it and retries, keeping the newer content, up to three times.
- The notification leaves the active lists and bells. The device's alert state in the live views is cleared.
- Acknowledging a running out-of-bed episode stops that episode from raising the alert again. A new bed exit raises a new alert.
- Answers 200 with the updated row, in the same shape as the list rows.
- A 409 means the notification kept changing and all three attempts lost the race. Re-read it and call again.
## Example
```bash
curl -X PATCH 'https://api.sandbox.ovok.com/v1/slim/notifications/c3499c27-2973-0a7f-807e-fb8676a92dcb/ack' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/Organization
- [Get organization](/api/slim/organization/get-organization): Returns one organization (a zone in the Slim dashboard) by id. Use it to show or edit a zone.
**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 `Organization:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The organization is read with the caller's own token, so you get any organization your Medplum access lets you read. There is no extra project check on this route.
## Behaviour
- Read-only.
- `description` is the organization's narrative text with the XHTML `` wrapper removed. It is absent when the organization has no narrative.
- `parentOrganizationId` is the id from `Organization.partOf`. It is absent for a top-level zone.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/organization/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{
"id": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"name": "Ward A",
"parentOrganizationId": "87ea5dfc-8b8e-384d-8489-79496e706390",
"description": "Ground floor"
}
```
- [Delete organization](/api/slim/organization/delete-organization): Deletes an organization (zone) and moves its residents, rooms and devices out of it.
**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 `Organization:delete` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The organization must belong to the caller's project (from the token).
## Behaviour
- The Organization resource is deleted.
- Every patient, location and device that references the zone is re-pointed:
- If the zone has a parent zone in your project, they move to the parent zone.
- Otherwise their zone reference is removed.
- Device use history is updated for any device whose assignment changes.
- The writes run in one bundle. Because a large zone can exceed the size limit of an atomic write, this route does not take the atomic write lock. A very large zone is written as a checked batch, so a partial failure is reported as an error rather than rolled back.
- A zone-deleted entry is added to the change history. A failure to write that entry does not fail the request.
- The response has no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/organization/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update organization](/api/slim/organization/update-organization): Updates an organization's (zone's) name, description and parent zone.
**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 `Organization:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The organization must belong to the caller's project (from the token). Organizations in a parent project or a sub-project are refused.
## Behaviour
- `name` is required and must be unique among the organizations your token can search, not counting this one.
- `parentOrganizationId` sets the parent zone. It must name an organization in your own project. **Omitting it removes the current parent**, which makes the zone top-level.
- `description`, when non-empty, replaces the narrative text. Omitting it, or sending `null` or an empty string, leaves the existing description unchanged.
- The write is atomic and takes a short write lock. A concurrent write to the same resources gets a 409.
- A zone-updated entry is added to the change history. A failure to write that entry does not fail the request.
- The response is the organization after the update, in the same shape as `GET /v1/slim/organization/{id}`.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/organization/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Ward A",
"parentOrganizationId": "87ea5dfc-8b8e-384d-8489-79496e706390",
"description": "Ground floor"
}'
```
- [Create organization](/api/slim/organization/create-organization): Creates an organization (a zone in the Slim dashboard), optionally as a child of another zone.
**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 `Organization:create` (an admin or super admin who holds no access policy skips this check).
**Scope:** The organization is created in the caller's project (from the token). A super-admin caller can pass `?projectId=` to create it in that project instead. Any other caller who passes `projectId` gets a 403.
## Behaviour
- `name` must be unique. The check is an exact name match against the organizations your token can search. With `?projectId`, the check runs in that project only.
- `parentOrganizationId`, when set, must name an organization in your own project. A sub-project's or parent project's organization is refused. The new zone's `partOf` points at it.
- `description`, when non-empty, is stored as the organization's narrative text. `null` or an empty string stores nothing.
- The write is atomic and takes a short write lock. A concurrent write to the same resources gets a 409.
- A zone-created entry is added to the change history. A failure to write that entry does not fail the request.
- The response is the created organization, in the same shape as `GET /v1/slim/organization/{id}`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/organization' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Ward A",
"parentOrganizationId": "87ea5dfc-8b8e-384d-8489-79496e706390",
"description": "Ground floor"
}'
```
- Slim/Patient
- [List patients](/api/slim/patient/list-patients): Lists the residents (patients) of your project with their zone, room, device and settings tags. Use it for the residents table in the Slim dashboard.
**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 `Patient:search`, `Patient:read`, `Device:read`, `Location:read` and `Organization:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). A token without a project is refused.
## Behaviour
- Read-only.
- One row per resident. When a resident is on several devices, the row shows one of them, so a resident is never listed twice.
- `residentState` defaults to `active`, so discharged residents are hidden unless you ask for them. `discharged-recent` means discharged within the last 30 days; `discharged` means longer ago. `all` turns the filter off.
- `includeDischargedRecent=true` widens `residentState=active` or `residentState=discharged` to also include `discharged-recent` residents.
- `organizationId` keeps residents in that zone. `hasDevice=true` keeps residents with a device; `hasDevice=false` keeps residents without one.
- `medicalSettings` and `bedActivitySettings` keep residents with that settings tag. These tags are `null` when Ovok could not read the project's threshold settings; such rows match no settings filter.
- `search` is a case-insensitive substring match on the resident's name, nickname, room name and zone name.
- Sort with `sortBy` (default `patientName`) and `orderBy` (`ASC` or `DESC`, any case, default `ASC`).
- Pagination is zero-based: `page` (default `0`) and `count` (default `20`, max `100`). `total` counts all matching rows.
- Fields with no value are `null`.
- Results are cached for up to 60 seconds per user. A change to a resident, device, room or zone made through Ovok clears the cache.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/patient?residentState=active&sortBy=patientNickname&orderBy=asc&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create patient](/api/slim/patient/create-patient): Creates a resident (patient), optionally placed on devices, in a room and in a zone, and registers them with Signals.
**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 `Patient:create`, plus `Device:update` when `deviceId` is set (an admin or super admin who holds no access policy skips this check).
**Scope:** The resident is created in the caller's project (from the token). A super-admin caller can pass `?projectId=` to create it in that project instead. Any other caller who passes `projectId` gets a 403. Devices, rooms and zones you reference must be in your project, its parent project, or one of its sub-projects.
## Behaviour
- `name` must contain an entry with `use: "nickname"` and a non-blank first `given` value. This is the Resident ID.
- The Resident ID must be unique in the project, compared as in `POST /v1/slim/patient/check-name-exists`.
- `admissionDate` defaults to now. It cannot be later than the start of the current day.
- The resident is created as `active`, and an `EpisodeOfCare` is opened for the admission.
- Placement:
- `deviceId` (one id or a list): the resident is assigned to those devices. A device that already has a resident is reassigned to the new one, and the resident who had it loses it, with its room, as on `PUT /v1/slim/patient/{id}`.
- `locationId` with `deviceId`: those devices are also moved to the room.
- `locationId` without `deviceId`: the resident is assigned to the room's device. The room must have exactly one device.
- `organizationId` without `locationId` or `deviceId` is refused with 422: a resident's zone is read from their device, so a zone alone would not show.
- `organizationId`: the resident is placed in the zone. When `deviceId` is set, those devices and their rooms move to the zone too.
- Without `organizationId`, the resident's zone is their device's: the room's zone, else the device's own. Devices in more than one zone are refused with 422.
- The resident is registered with Signals in the same request. If that fails, everything this request wrote is rolled back and you get a 503 with `error: "signals_mint_failed"`. You can retry.
- The write is atomic and locks the Resident ID and the devices, so two concurrent creates of the same Resident ID leave one resident.
- Change-history entries are added for each assignment, including the zone the resident gets from their device, and for a resident who lost a device to the new one.
- The response is the created resident, in the same shape as `GET /v1/slim/patient/{id}`.
- If the resident cannot be registered with Signals, the create is rolled back and the request fails with 503. Retry it.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/patient' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": [
{ "use": "nickname", "given": ["Maxi"] },
{ "use": "official", "given": ["Max"], "family": "Mustermann" }
],
"gender": "male",
"birthDate": "1940-05-01",
"deviceId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"locationId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390"
}'
```
- [Get patient current vitals](/api/slim/patient/get-patient-current-vitals): Returns the latest live telemetry for a resident: one entry per device assigned to them, with the device, resident and zone.
**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 `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token). A resident outside that project returns `total: 0` and no entries.
## Behaviour
- Read-only.
- Returns one entry per device assigned to the resident, up to 100. A resident with no device returns `total: 0`.
- The response is cached for up to 60 seconds, so `telemetry` can lag the latest reading by up to a minute.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/patient/c3499c27-2973-0a7f-807e-fb8676a92dcb/current-vitals' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get patient $everything](/api/slim/patient/get-patient-everything): Returns a FHIR `Bundle` with the resident and every resource that references them, using the FHIR `Patient/$everything` operation. Use it to export or inspect a resident's full record.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The resident must belong to the caller's project (from the token) or one of its sub-projects. A resident in the parent project is refused.
## Behaviour
- Read-only.
- The bundle is produced by Medplum and read with the caller's own token, so it contains only resources that token can read.
- The response is a raw FHIR `Bundle`, not a Slim DTO.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/patient/c3499c27-2973-0a7f-807e-fb8676a92dcb/$everything' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get patient](/api/slim/patient/get-patient): Returns one resident (patient) by id, with their names, resident state and current placement. The response is the shape `PUT /v1/slim/patient/{id}` accepts back.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The resident is read with the caller's own token, so you get any patient your Medplum access lets you read. There is no extra project check on this route.
## Behaviour
- Read-only.
- `deviceId` is one device id, or `null` when the resident has no device. If the resident is on several devices, it is the most recently updated one. `locationId`, `floor`, `room`, `bed` and `organizationId` describe that same device's placement.
- `residentState` is `active`, `discharged-recent` (discharged within the last 30 days), `discharged` or `archived`.
- `admissionDate` and `dischargeDate` are returned as stored.
- A `name` entry without a `use` is returned as `official`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/patient/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Delete patient](/api/slim/patient/delete-patient): Deletes a resident (patient) who has no device.
**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 `Patient:delete` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The resident must belong to the caller's project (from the token).
## Behaviour
- A resident who still has a device is refused with 409 `Resident still has device . Unassign it first.`, and nothing is changed. Take the device off the resident first (`PUT /v1/slim/patient/{id}` without `locationId`), then delete.
- Only the Patient resource is deleted. This route does not delete the resident's other records.
- Archived residents cannot be deleted.
- A change-history entry records the delete.
- The response has no body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/patient/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update patient](/api/slim/patient/update-patient): Updates a resident (patient): names, gender, birth date, placement on devices, room and zone, and resident state (discharge or reactivation).
**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 `Patient:update`, plus `Device:update` when the request changes which devices the resident is on (an admin or super admin who holds no access policy skips this check).
**Scope:** The resident must belong to the caller's project (from the token). Devices, rooms and zones you reference must be in your project, its parent project, or one of its sub-projects.
## Behaviour
The body is a full replacement of the editable fields, designed so that the result of `GET /v1/slim/patient/{id}` can be sent back unchanged. Fields the update does not declare, such as `id`, `floor` or `admissionDate`, are ignored.
- `name` replaces all of the resident's names, each trimmed of leading and trailing spaces. It must contain a `nickname` entry with a non-blank first `given` value. If the nickname changes, it must be unique in the project.
- `gender` and `birthDate` are replaced. Omitting them, or sending `""`, clears them.
- **Placement depends on `locationId`:**
- **`locationId` omitted or `""`: the resident is removed from all of their devices**, and `deviceId` and `organizationId` are ignored. Send the current `locationId` to keep the placement.
- `locationId` with `deviceId`: the resident is placed on those devices, and the devices move to the room. The resident leaves any other device. A resident already on one of those devices is replaced.
- `locationId` without `deviceId`: the resident is placed on the room's device. The room must have exactly one device.
- `locationId` with `deviceId` `null`, `[]` or `""` is refused with 422 and changes nothing: a room is not a placement without a device.
- A resident in a room is in the room's zone. An `organizationId` that differs from the zone of the room the resident stays in answers 422 with `path: ["organizationId"]` and changes nothing: move the room to that zone with `PUT /v1/slim/location/{id}`, or the resident to a room in it. A resident moving to another room takes that room's zone. When the room has no zone, `organizationId` re-zones the resident's devices.
- A save that puts the resident on devices in more than one zone, when they were not in exactly those zones before, is refused with 422.
- A discharged resident (`discharged` or `discharged-recent`) placed on a device they are not on is refused with 422 and nothing changes, with or without `deviceId`. Send `residentState: "active"` in the same save to reactivate and place them.
- `residentState`:
- `discharged` on an active resident: the resident is tagged discharged, `dischargeDate` is stored (default: now), the `EpisodeOfCare` is finished, and the resident is removed from all devices. `locationId` must be omitted or `""`.
- `discharged` on a resident already discharged: only a different `dischargeDate` has an effect; it corrects the stored date.
- `active` on a discharged resident: the resident is reactivated, the latest `EpisodeOfCare` is reopened and `dischargeDate` is removed.
- Other values, or the current state, change nothing.
- Any resident who loses a device in this request has their active out-of-bed notification revoked in the same write, and the device's live telemetry state is cleared afterwards.
- Archived residents cannot be updated.
- The write is atomic and takes a short write lock on the resident, the devices and, on a rename, the new Resident ID.
- Change-history entries are added for each changed field and assignment. A resident replaced on a device gets one naming the device, and the room and zone they leave with it.
- The response is the resident after the update, in the same shape as `GET /v1/slim/patient/{id}`.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/patient/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": [{ "use": "nickname", "given": ["Maxi"] }],
"gender": "male",
"birthDate": "1940-05-01",
"deviceId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"locationId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390",
"residentState": "active"
}'
```
- [Check patient name exists](/api/slim/patient/check-patient-name-exists): Checks whether a Resident ID (the resident's nickname) is already used in your project. Use it to validate the Resident ID field before you create or rename a resident.
**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 `Patient:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** Residents in the caller's project (from the token).
## Behaviour
- Read-only.
- Only the `name` entry with `use: "nickname"` is compared. Official and maiden names are ignored. Without a nickname entry the answer is `exists: false`.
- A match needs the same `given` tokens in the same order and the same `family` (or no `family` on both sides). Tokens are trimmed and compared case-insensitively.
- When you edit an existing resident, pass their id as `excludePatientId` so their own record does not count as a match.
- The create and update routes run the same check, so a `true` here means those requests would be refused with a 422.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/patient/check-name-exists' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": [{ "use": "nickname", "given": ["Maxi"] }],
"excludePatientId": "c3499c27-2973-0a7f-807e-fb8676a92dcb"
}'
```
```json
{ "exists": false }
```
- Slim/Policy
- [List access policies](/api/slim/policy/list-access-policies): Lists the access policies (roles) of a project, each with the practitioners who hold it. Use it to render a roles table.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:create`, the right to invite users (a project admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token), or `projectId` when given. `projectId` must be the caller's project or a direct child of it.
## Behaviour
- Each row is `{ policy, members }`. `members` lists only `Practitioner` members, as `{ reference, display }`.
- `profile` keeps only the policies held by that member, given as a reference such as `Practitioner/`.
- `sortBy` is `_id` (default), `_lastUpdated` or `name`; `orderBy` is `ASC` (default) or `DESC`. Rows with an empty sort value go last in `ASC` and first in `DESC`.
- Paging is in memory: `page` (default `0`) and `count` (default `20`, 1 to 100). `total` counts the rows after filtering, before paging.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/policy?sortBy=name&orderBy=ASC&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create access policy](/api/slim/policy/create-access-policy): Creates an access policy (role) in your project and assigns it to the listed practitioners. Use it to define a new role.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `AccessPolicy:create` and `ProjectMembership:update` (a project admin who holds no access policy skips this check).
**Scope:** The policy is created in the caller's project (from the token).
## Behaviour
- You cannot create a policy above your own rank. Ranks come from the policy name or its `basedOn` display: `System Owner` is the highest, then `Admin`, then every other policy. Project admins rank as System Owner.
- Ovok adds interactions the apps rely on:
- `Consent`: `read`, `search`, `create`, `update`, always;
- `DeviceUseStatement` and `EpisodeOfCare`: `read`, `search`, `create`, `update`, when the policy may create or update `Patient`;
- `Provenance` and `AuditEvent`: `read`, `search`, when the policy is named `Admin` or `System Owner`.
- `members` are profile references such as `Practitioner/`. Each listed member's membership in your project now points to the new policy, replacing the policy it held before. A member with no membership in your project is skipped.
- You cannot list a member whose current role ranks above yours. A member ranks as every policy their membership holds now (`accessPolicy` and any `access` entries), each ranked by its name. A project admin (`admin: true`) ranks as System Owner.
- The policy and the membership changes commit together. Past 49 membership changes they are written in two steps.
- The policy is then copied by name into each direct child project. A failed copy does not fail the request.
- Returns the created policy with its members, as in `GET /v1/slim/policy/{id}`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/policy' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"policy": {
"resourceType": "AccessPolicy",
"name": "Night shift",
"resource": [{ "resourceType": "Patient", "interaction": ["read", "search"] }]
},
"members": [{ "reference": "Practitioner/c3499c27-2973-0a7f-807e-fb8676a92dcb", "display": "Max Mustermann" }]
}'
```
- [Get access policy](/api/slim/policy/get-access-policy): Returns one access policy (role) with the practitioners who hold it.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:create`, the right to invite users (a project admin who holds no access policy skips this check).
**Scope:** The policy must belong to the caller's project (from the token), its parent project or one of its direct child projects.
## Behaviour
- Returns `{ policy, members }`. `policy` is the full `AccessPolicy`. `members` lists the `Practitioner` members whose membership points to it, as `{ reference, display }`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/policy/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Delete access policy](/api/slim/policy/delete-access-policy): Deletes an access policy (role) of your project and detaches it from everyone who holds it.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `AccessPolicy:delete` and `ProjectMembership:update` (a project admin who holds no access policy skips this check).
**Scope:** The policy must belong to the caller's project (from the token).
## Behaviour
- A policy is not deleted while a holder would be left with no role (no `access` entry, not a project admin): the request answers 409 until they are moved to another role, because Medplum reads a membership with no policy as full access. Other holders are detached.
- You cannot delete a policy you hold yourself.
- You cannot delete a policy held by anyone whose role ranks above yours (a project admin ranks as System Owner), since that takes their role away.
- Detaching the members and deleting the policy commit together. Past 49 membership changes they are written in two steps.
- The policy's copies of the same name in direct child projects are then deleted. A failed copy delete does not fail the request.
- Returns an empty body.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/policy/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update access policy](/api/slim/policy/update-access-policy): Replaces an access policy (role) of your project and sets exactly which practitioners hold it.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:create`, the right to invite users (a project admin who holds no access policy skips this check).
**Scope:** The policy must belong to the caller's project (from the token). Policies of parent or child projects can be read but not updated here.
## Behaviour
- `policy.id` must equal the `id` in the path.
- The policy body is replaced with `policy`. The same interactions as on create are added (`Consent`; `DeviceUseStatement` and `EpisodeOfCare` for policies that create or update `Patient`; `Provenance` and `AuditEvent` for `Admin` and `System Owner` policies).
- You cannot update a policy that ranks above you, nor rename one to a rank above you. Ranks: `System Owner`, then `Admin`, then every other policy.
- You cannot add or remove a member whose current role ranks above yours. A member ranks as every policy their membership holds now (`accessPolicy` and any `access` entries), each ranked by its name. A project admin (`admin: true`) ranks as System Owner.
- `members` is the complete list of holders, as references such as `Practitioner/`:
- a listed member's membership in your project now points to this policy, replacing the one it held;
- a current holder not listed loses the policy. Medplum reads a membership with no policy as full access, so if that would leave them with none (no `access` entries, not a project admin), the request answers 409: move them to another role first;
- you cannot remove yourself.
- The policy and the membership changes commit together. Past 49 membership changes they are written in two steps.
- The updated policy is then copied by name into each direct child project, also when it was renamed. A failed copy does not fail the request.
- Returns the updated policy with its members.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/policy/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"policy": {
"resourceType": "AccessPolicy",
"id": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"name": "Night shift",
"resource": [{ "resourceType": "Patient", "interaction": ["read", "search", "update"] }]
},
"members": [{ "reference": "Practitioner/c3499c27-2973-0a7f-807e-fb8676a92dcb" }]
}'
```
- Slim/Practitioner
- [Get practitioner](/api/slim/practitioner/get-practitioner): Returns a practitioner profile by id. Use it to show your own profile or, with the extra permission, another practitioner's.
**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 `Practitioner:read`. Reading another practitioner's profile also needs `Practitioner:update`. An admin or super admin who holds no access policy skips the access-policy check.
**Scope:** Your own profile is always readable. Another practitioner must belong to your project, one of its sub-projects, or its parent project.
## Behaviour
- Read-only.
- Your own profile is read with your token. Another practitioner's profile is read with Ovok's admin client after the project check above passes.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/practitioner/87ea5dfc-8b8e-384d-8489-79496e706390' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update practitioner](/api/slim/practitioner/update-practitioner): Updates a practitioner profile: name, surname, email, phone, address and photo.
**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 `Practitioner:read`. Updating another practitioner's profile also needs `Practitioner:update`. An admin or super admin who holds no access policy skips the access-policy check.
**Scope:** You can always update your own profile. Another practitioner must belong to your project, one of its sub-projects, or its parent project.
## Behaviour
- The Practitioner resource is **replaced** with one built from the body. A field you omit is cleared, and FHIR fields that the body cannot carry are not kept. Send the full profile, for example the result of `GET /v1/slim/practitioner/{id}` with your changes applied.
- `id` in the body is optional. When present it must equal the `id` in the path.
- `meta` in the body is ignored. Ovok sets `meta.author` to the caller.
- `email` is stored in lower case.
- This route does not change roles or access policies.
- Your own profile is written with your token. Another practitioner's profile is written with Ovok's admin client after the project check above passes.
- The response is the updated profile.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/practitioner/87ea5dfc-8b8e-384d-8489-79496e706390' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Max",
"surname": "Mustermann",
"email": "max.mustermann@example.com",
"phone": "+491234567890"
}'
```
- Slim/Project
- [List current project users](/api/slim/project/list-current-project-users): Lists the practitioner memberships of your current project, with each member's user, profile, access policy and invite status. Use it to render a project's team list.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:read` (a project admin who holds no access policy skips this check). The session must carry a project.
**Scope:** The caller's project (from the token).
## Behaviour
- Returns one row per `ProjectMembership` of `profileType` (`Practitioner`) that has both a user and a profile. Memberships whose user or profile cannot be resolved are left out.
- `status` is `Pending` while the user has an unused invite or has never set a password, and `Active` otherwise.
- `accessPolicyId`, `profileId` and `userId` narrow the memberships by exact id.
- `search` is a fuzzy match over the profile name, the user name and the access policy name.
- `sortBy` defaults to `profileName` and `orderBy` to `ASC`. Rows with an empty sort value go last in `ASC` and first in `DESC`.
- Paging is in memory: `page` (default `0`) and `count` (default `20`, 1 to 100). `total` counts the rows after `search`, before paging.
- Answers are cached for up to about a minute, so a member added or removed a moment ago can be missing or still listed.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/users?sortBy=userName&orderBy=ASC&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List child project relationships](/api/slim/project/list-child-project-relationships): Returns your current project together with its parent project and its direct child projects. Use it to build a project switcher or hierarchy view.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `AccessPolicy:read` (a project admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- `currentProject` is the caller's project.
- `parentProject` is the project your project is a child of, or `null` when it has none.
- `childProjects` lists every direct child, with no cap. Grandchildren are not included.
- A child whose project no longer exists is left out.
- Each project carries `name` (the project id when it has none), `address`, `contact` and `settings`. `settings.timeZone` defaults to `Europe/Berlin`; `settings.trendsPeriod` defaults to `start: "09:00:00"` and `durationSeconds: 86400`.
- `GET /v2/slim/project/child` returns the same lists with a device count per project.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/child' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create a child project](/api/slim/project/create-a-child-project): Creates a child project under your current project and makes you its admin. Use it to set up a new customer or site below your organisation.
**Auth:** Bearer token for a project admin. No other role passes.
**Scope:** The new project becomes a direct child of the caller's project (from the token). A project that is itself a child may create children of its own.
## Behaviour
- Your project must already hold at least one access policy: the child gets a copy of every access policy of your project. Without one the request is refused with 424 and nothing is created.
- A second child with exactly the same `name` under the same parent is refused with 422.
- The whole create is all or nothing. A failure undoes what was written and answers the failure.
- On success Ovok:
- creates the project with practitioner invitations and practitioner login enabled, and practitioner registration plus all patient registration, invitation and login disabled;
- gives it its own Signals tenant and its own tenant code;
- links it to your project;
- copies your practitioner profile into it and adds you as an admin member;
- seeds its thresholds from the global defaults, with an out-of-bed window that ends at 09:00 and starts at a time picked once from 18:00 to 20:00 in 5-minute steps, so homes do not all start watching in the same minute. The start is stored and stays until someone saves another window;
- gives its Signals tenant the derived readings: each resident's daily mean heart rate and breathing rate (local midnight to midnight) and last night's sleep period, scheduled in the project's time zone.
- The organization stored inside the project is built from `name`, `address`, `contact` and `settings`. `settings.timeZone` must be an IANA time zone such as `Europe/Zurich` (any other value is refused with 422) and defaults to `Europe/Berlin`. `id` and `extension` in the body are ignored.
- When Signals cannot take the derived readings, the create is undone and answers 502, 503 when Signals is overloaded, or 504 when it does not answer in time.
- When the platform has it enabled, an Ovok support account is also added as a non-admin member holding the child's System Owner access policy. It is skipped when the child has no single policy of that name. This step never fails the create.
- Child project lists are refreshed right away.
- Returns `{ "projectId": "", "success": true }`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/project/child' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "My Medical Project",
"contact": [{ "telecom": [{ "system": "email", "use": "work", "value": "max.mustermann@example.com" }] }],
"settings": { "timeZone": "Europe/Berlin" }
}'
```
```json
{ "projectId": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "success": true }
```
- [List child projects with device counts](/api/slim/project/list-child-projects-with-device-counts): Returns your current project together with its parent project and its direct child projects, each with its device count. Use it for a project switcher or hierarchy view that shows fleet size.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `AccessPolicy:read` (a project admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Same lists as `GET /v1/slim/project/child`: `currentProject`, `parentProject` (`null` when there is none) and every direct child in `childProjects`. Grandchildren and children whose project no longer exists are left out.
- Every project also carries `deviceCount`: the number of `Device` resources in that project.
- `settings.timeZone` defaults to `Europe/Berlin`; `settings.trendsPeriod` defaults to `start: "09:00:00"` and `durationSeconds: 86400`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v2/slim/project/child' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Delete a child project](/api/slim/project/delete-a-child-project): Deletes an empty direct child project of your current project, including the setup Ovok created with it. Use it to remove a child project that is no longer needed.
**Auth:** Bearer token for a project admin. No other role passes.
**Scope:** `subProjectId` must be a direct child of the caller's project (from the token).
## Behaviour
- The child must be empty: no `Patient`, `Device` or `Location`, and no child projects of its own. Otherwise the request is refused with 409 and nothing is changed. The 409 body has `error: "project_not_empty"`, a `counts` object per resource type and the `childProjectIds`.
- On success Ovok unlinks the child from your project, deletes its access policies, practitioners, memberships, threshold plan, client applications, top-level organizations and tenant code, deletes the project, then revokes its Signals tenant.
- User accounts are never deleted: a user can belong to other projects. Audit records (`Provenance`, `AuditEvent`) are kept.
- Two deletes of the same project cannot run at once: the second gets 409.
- The delete is safe to retry. If the Signals revoke fails, the project is already deleted and the request answers 502. Send the same request again to finish it.
- Returns `{ "success": true }`.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/project/child/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List project users](/api/slim/project/list-project-users): Lists the practitioner memberships of a given project: your own project or one of its direct child projects. Use it to manage the team of a child project from its parent.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:read` (a project admin who holds no access policy skips this check). The session must carry a project.
**Scope:** The project in the path. It must be the caller's project (from the token) or a direct child of it. Grandchildren are not reachable.
## Behaviour
- The project is read first, so an unknown or out-of-scope `id` fails before any membership is searched.
- Rows, filters, sorting, paging and `status` work exactly as in `GET /v1/slim/project/users`: one row per `Practitioner` membership with a user and a profile, `search` is fuzzy over profile, user and access policy names, `count` is 1 to 100 (default `20`).
- Answers are cached for up to about a minute.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/c3499c27-2973-0a7f-807e-fb8676a92dcb/users?count=50' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get project device counts](/api/slim/project/get-project-device-counts): Returns summary counts of the devices in a project: total, assigned to a resident, active and by manufacturer. Use it for project overview tiles.
**Auth:** Bearer token. The caller's access policy must grant `Device:search` and `Device:read` (a project admin who holds no access policy skips this check).
**Scope:** The project in the path. It must be the caller's project (from the token) or a direct child of it.
## Behaviour
- Counts come from the project's live device list, the same rows that back the live device views. That list is cached, so a device change can take a moment to show.
- A row is left out when its device, resident, location or organization belongs to another project.
- `assignedResidentDeviceCount` counts devices with a resident; `unassignedDeviceCount` is the rest.
- `activeDeviceCount` counts devices whose latest telemetry reports them active; `inactiveDeviceCount` is the rest.
- `withingsDeviceCount` counts devices whose serial number resolves to Withings. Every other device is counted in `radarDeviceCount`.
- If the device list fails to build, the last complete list is used.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/c3499c27-2973-0a7f-807e-fb8676a92dcb/device-counts' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get project patient counts](/api/slim/project/get-project-patient-counts): Returns summary counts of the residents in a project by state: active, recently discharged, discharged and archived. Use it for project overview tiles.
**Auth:** Bearer token. The caller's access policy must grant `Patient:search` and `Patient:read` (a project admin who holds no access policy skips this check).
**Scope:** The project in the path. It must be the caller's project (from the token) or a direct child of it.
## Behaviour
- Counts come from the project's live device list, so only residents linked to a device row are counted. A resident without a device is not included.
- Each resident is counted once, even when linked to several devices.
- A row is left out when its device, resident, location or organization belongs to another project.
- The device list is cached, so a change can take a moment to show. If the list fails to build, the last complete list is used.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/c3499c27-2973-0a7f-807e-fb8676a92dcb/patient-counts' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get a project](/api/slim/project/get-a-project): Returns a project's name, address, contact and settings. Use it to show or edit your project or one of its child projects.
**Auth:** Bearer token. The caller's access policy must grant `AccessPolicy:read` and `AccessPolicy:update` (a project admin who holds no access policy skips this check).
**Scope:** The project in the path. It must be the caller's project (from the token) or a direct child of it.
## Behaviour
- `address` and `contact` come from the organization stored inside the project.
- `name` falls back to the project id when the project has no name.
- `settings.timeZone` defaults to `Europe/Berlin` when none is stored.
- `settings.trendsPeriod` defaults to `start: "09:00:00"` and `durationSeconds: 86400` when none is stored.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/project/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update a project](/api/slim/project/update-a-project): Updates a project's name, address, contact and settings, and returns the updated project. Use it to edit your project or one of its child projects.
**Auth:** Bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** The project in the path. It must be the caller's project (from the token) or a direct child of it.
## Behaviour
- Sets the project `name` and replaces the organization stored inside the project with one built from `name`, `address`, `contact` and `settings`. This is a full replace, not a merge:
- an omitted `address` or `contact` clears it;
- an omitted `settings.timeZone` resets the time zone to `Europe/Berlin`;
- an omitted `settings.trendsPeriod` removes the stored trends period, so reads fall back to the default.
- `id` and `extension` in the body are ignored. The project comes from the path.
- `settings.trendsPeriod.start` must be `HH:MM:SS`.
- The response has the shape of `GET /v1/slim/project/{id}`.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/project/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "My Medical Project",
"address": [{ "line": ["Hauptstrasse 1"], "city": "Berlin", "postalCode": "10115", "country": "DE" }],
"settings": { "timeZone": "Europe/Berlin", "trendsPeriod": { "start": "09:00:00", "durationSeconds": 86400 } }
}'
```
- Slim/Query
- [List devices with telemetry (compatibility)](/api/slim/query/list-devices-with-telemetry-compatibility): Compatibility route for older query clients. Returns device rows joined with their resident, location, zone and telemetry. For new integrations, use `GET /v1/slim/device/live` or the `/v1/slim/patient` routes.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token). The `project` parameter is ignored.
## Behaviour
- `mustInclude` lists the resources a row must have to be returned. `shouldInclude` lists the resources added to each row when present. Both are comma-separated lists of `organization`, `device`, `location`, `patient` and `telemetry`.
- Every entry in `mustInclude` must also be in `shouldInclude`. `telemetry` in either list needs `device` in the same list.
- When `mustInclude` contains `patient`, the query runs on the older resident-oriented path, which reads telemetry from the device database and Redis. Otherwise it runs on the same path as `GET /v1/slim/device/live`.
- Without `includeUnassigned=true`, rows without a resident are left out when `patient` is required.
- `organization` takes `Organization/`, `assigned` or `unassigned`.
- `page` is zero-based. `count` defaults to 20, maximum 100.
- The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/query?mustInclude=device,telemetry&shouldInclude=organization,device,location,patient,telemetry&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List telemetry and alerts (compatibility)](/api/slim/query/list-telemetry-and-alerts-compatibility): Compatibility route for older live polling clients. Returns telemetry and alerts maps keyed by device identifier. For new integrations, use `GET /v1/slim/device/live/telemetry`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token). The `project` parameter is ignored.
## Behaviour
- Takes the same query parameters as `GET /v1/slim/query`, with the same validation rules.
- Returns `total`, plus `telemetry` and `alerts` for the requested page only.
- `alerts` has an entry for every device on the page. `telemetry` has an entry only for devices with telemetry.
- The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/query/telemetry?mustInclude=device,telemetry&shouldInclude=device,telemetry' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get resident devices with telemetry (compatibility)](/api/slim/query/get-resident-devices-with-telemetry-compatibility): Compatibility route for older resident vitals clients. Returns the devices assigned to one resident, each with its telemetry. For new integrations, use `GET /v1/slim/patient/{id}/current-vitals`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`.
**Scope:** the caller's project (from the token). The `project` parameter is ignored.
## Behaviour
- Returns up to 100 device rows for the resident, with zone, device and telemetry.
- Results are cached for up to 60 seconds. Writes made through the Slim routes refresh the cache sooner.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/query/patient/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Count devices per zone (compatibility)](/api/slim/query/count-devices-per-zone-compatibility): Compatibility route for older zone count clients. Returns device counts per zone. For new integrations, use `GET /v1/slim/zones/device-counts`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Organization:search` and `Device:search`.
**Scope:** the caller's project (from the token). For admins, the counts also cover the project's sub-projects.
## Behaviour
- Each entry has the zone (`organization`) and its `deviceCount`, `assignedResidentDeviceCount`, `activeDeviceCount` and `inactiveDeviceCount`.
- Devices without a zone are counted in an entry without `organization`.
- Only zones with at least one device are listed, sorted by `deviceCount`, highest first.
- A device counts as active when its telemetry reports it active.
- The top-level `total*` fields sum the counts over all entries. `total` is the number of entries.
- Results are cached for up to 60 seconds. Writes made through the Slim routes refresh the cache sooner.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/query/organization/device/count' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List users (compatibility)](/api/slim/query/list-users-compatibility): Compatibility route for older user list clients. Lists the practitioner users of a project with their profile, membership and access policy. For new integrations, use `GET /v1/slim/project/users`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Practitioner:read`.
**Scope:** the caller's project (from the token). When you pass `project=Project/`, that project is used instead. It must be your project or one of its sub-projects.
## Behaviour
- `profileType` is required and must be `Practitioner`.
- Each row has `user`, `profile`, `membership` and, when set, `accessPolicy`, reduced to the fields a list needs.
- A user's status is `Pending` when they have an unused invite or no password yet, otherwise `Active`.
- `accessPolicy`, `profile` and `user` filter on exact references, for example `AccessPolicy/`.
- `search` matches profile name, user name and access policy name, with fuzzy matching.
- `page` is zero-based. `count` defaults to 20, maximum 100.
- Results are cached for up to 60 seconds.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/query/user?profileType=Practitioner&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List users across projects (compatibility)](/api/slim/query/list-users-across-projects-compatibility): Compatibility route for older cross-project user list clients. Behaves exactly like `GET /v1/slim/query/user`. For new integrations, use `GET /v1/slim/project/{id}/users`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Practitioner:read`. No extra admin check is applied.
**Scope:** the caller's project (from the token), or the project in `project=Project/` when it is your project or one of its sub-projects.
## Behaviour
- Same parameters, filters, sorting, paging and caching as `GET /v1/slim/query/user`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/query/admin/user?profileType=Practitioner&project=Project/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/Sleep
- [Get sleep statistics](/api/slim/sleep/get-sleep-statistics): Returns a resident's sleep statistics for one night, grouped by device, with each metric compared against the average of the preceding nights. Use it for the sleep detail view.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Observation:read` and `Observation:search`.
**Scope:** the caller's project (from the token). Sleep data is read with your token, so Medplum's access policy limits what you see.
## Behaviour
- The "night" is the calendar day, in the project's time zone, of `endDate`. A sleep recording belongs to the day its `effectivePeriod.end` falls on.
- `lastDayCount` is how many earlier days feed `average`. It defaults to `7` and must be between 1 and 30.
- Each device entry holds, per metric, `current` (the night of `endDate`), `average` (over the earlier nights that have a recording) and `diff`. A device with no recording for the night of `endDate` is left out.
- When one night has several recordings, the one written last is used: the latest `meta.lastUpdated`. Its period and completeness do not count, so a shorter recording written later wins, and so can a same-day nap ending after the night. A metric it does not carry is `null`, never taken from another recording. The PDF export's sleep table uses the same rule, and so do the `GET /v1/slim/trends/graphs` charts where they can match a night's readings to its recordings.
- `average` and `diff` use each earlier night's latest-written recording the same way.
- Only recordings that end inside one of the resident's use periods of their device are counted, before a night's recording is picked. So a previous resident's night that ended before the device was handed over, but reached Ovok after it and was stored under this resident, is not shown. A resident with no device use history has all recordings counted. The PDF export and the `GET /v1/slim/trends/graphs` charts apply the same filter.
- Once a resident has any use period, recordings of a device with no period of theirs, and those from before a device's earliest period, are not counted. A device assigned before use periods were recorded gets its first one on its next edit in Ovok, starting at the Device's last write before that edit. Each device whose recordings in a request all drop is counted in the `sleep.device_use_device_dropped` metric and logged at most once a minute.
- Ovok reads the `sleep-stats` observations first and falls back to the LOINC pair `93832-4` (sleep duration) and `103216-8` (out-of-bed count) when there are none.
- The response is `{}` when no qualifying recording exists.
- Results are cached for up to 60 seconds per project, resident, `endDate` and `lastDayCount`. A write to the resident's data invalidates the cache sooner.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/sleep/statistics?patientId=c3499c27-2973-0a7f-807e-fb8676a92dcb&endDate=2026-09-28T00:00:00Z&lastDayCount=7' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/Telemetry
- [List effective observation ids by device](/api/slim/telemetry/list-effective-observation-ids-by-device): Returns the effective Observation ids for every device in your project, keyed by device identifier. These are the readings that produced each device's current heart rate, respiratory rate, sleep status and presence values.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read` and `Device:search`.
**Scope:** the caller's project (from the token).
## Behaviour
- Covers the devices that have telemetry, up to the first 1000 devices of the project, including devices without a resident.
- Each value has the same shape as `GET /v1/slim/telemetry/{deviceId}/effectiveIds`. Fields are `null` when no reading has set them.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/telemetry/effectiveIds' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List last-received observation ids by device](/api/slim/telemetry/list-last-received-observation-ids-by-device): Returns the last-received Observation ids for every device in your project, keyed by device identifier.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read` and `Device:search`.
**Scope:** the caller's project (from the token).
## Behaviour
- Covers the devices that have telemetry, up to the first 1000 devices of the project, including devices without a resident.
- Each value has the same shape as `GET /v1/slim/telemetry/{deviceId}/lastIds`. Fields are `null` when nothing has been received for them.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/telemetry/lastIds' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get effective observation ids for a device](/api/slim/telemetry/get-effective-observation-ids-for-a-device): Returns, for one device, the ids of the Observations that produced its current heart rate, respiratory rate, sleep status and presence values. Use it to trace a displayed value back to its source reading.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read`.
**Scope:** a device identifier only resolves when the device is visible to your token and in the caller's project.
## Behaviour
- `deviceId` is either the device identifier or the Device resource id (a UUID).
- Each field is an Observation id, or `null` when no reading has set that value yet.
- Only devices whose readings carry their own Observation id fill these fields. For other devices every field is `null`.
- A device that is not found returns every field `null`, not an error.
- Lookups of a device are cached for up to 10 minutes, and misses for 30 seconds.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/telemetry/c3499c27-2973-0a7f-807e-fb8676a92dcb/effectiveIds' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get last-received observation ids for a device](/api/slim/telemetry/get-last-received-observation-ids-for-a-device): Returns, for one device, the ids of the most recent Observations received for heart rate, respiratory rate, sleep status and presence, plus the latest batch. Unlike `effectiveIds`, these change on every reading, whether or not the displayed value changed.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read`.
**Scope:** a device identifier only resolves when the device is visible to your token and in the caller's project.
## Behaviour
- `deviceId` is either the device identifier or the Device resource id (a UUID).
- Each field is an Observation id, or `null` when nothing has been received for it yet.
- Only devices whose readings carry their own Observation id fill these fields. For other devices every field is `null`.
- A device that is not found returns every field `null`, not an error.
- Lookups of a device are cached for up to 10 minutes, and misses for 30 seconds.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/telemetry/c3499c27-2973-0a7f-807e-fb8676a92dcb/lastIds' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get device telemetry and alerts](/api/slim/telemetry/get-device-telemetry-and-alerts): Returns the current telemetry and alerts for one device. Use it to poll the resident detail view.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:read`.
**Scope:** the caller's project (from the token). Only devices in that project are found.
## Behaviour
- `deviceId` is either the device identifier (for example `Sleepiz/3001000`) or the Device resource id (a UUID). A UUID is resolved to the identifier.
- The response `deviceId` is the identifier the telemetry is keyed by.
- `telemetry` and `alerts` have the same shape as one entry of `GET /v1/slim/device/live/telemetry`.
- The device is looked up among the first 1000 devices of your project, including devices without a resident.
- Telemetry is read fresh on every request.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/telemetry/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/Threshold
- [Get current threshold](/api/slim/threshold/get-current-threshold): Returns the home's threshold configuration: the alert limits every resident follows unless they have limits of their own.
> **Deprecated.** Use `GET /v2/slim/threshold`. 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 `PlanDefinition:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Read-only.
- A home that has never saved thresholds gets the default template, with no `id`: heart rate on at 40–110 and respiratory rate on at 8–25 (the limits a new home is seeded with), and every other metric disabled.
- If the stored thresholds cannot be read, the route answers 502, never the default template.
- Units: `durationOfOutOfBed` is in seconds, `sleepDuration` in hours.
- The home's limit ranges and the optional vitals (SpO₂, pulse rate, perfusion index, body temperature) are only on the v2 route.
- Heart-rate and respiratory-rate limits are evaluated by Signals. Ovok stores them and forwards them to Signals.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/threshold' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update threshold](/api/slim/threshold/update-threshold): 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`. 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` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- The body replaces the stored settings; fields you omit take their schema defaults, except the out-of-bed window: a body without `durationOfOutOfBed.period`, or without `durationOfOutOfBed`, keeps the home's stored window (19:00:00 to 09:00:00 when it has none). The home's limit ranges and optional vitals, which v1 cannot send, are kept as stored.
- 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. One sent under `enabled: false` is stored off.
- Every limit is evaluated by Signals, so every save is all or nothing, as `PUT /v2/slim/threshold` describes: it answers once Signals holds the home's limits, which every resident following the home follows at once, or puts everything back and answers an error with `saved: false` (409 another save or a tenant move got in the way; 502 out of time, or Signals did not take them; 500 the undo failed too). Nothing is stored then; send the save again. A 504 from the gateway can come while a failed save is still being put back: read the limits before sending it again.
- A change-history entry is written for a save that stands.
- The response is the saved configuration.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/threshold' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"status": "active",
"settings": {
"heartRate": { "mode": "organization", "enabled": true, "absolute": { "enabled": true, "min": 40, "max": 120 } }
}
}'
```
- Slim/Trends
- [Get trends graphs](/api/slim/trends/get-trends-graphs): Returns a resident's heart rate and respiratory rate over a date range, grouped by graph type and device, with threshold and baseline values and summary statistics. Use it to draw the trend charts. For live readings from the last day, use `GET /v1/slim/trends/realtime`.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Organization:read`, `Device:read`, `Patient:read` and `DocumentReference:read`.
**Scope:** the caller's project (from the token). Observations are read with your token, so Medplum's access policy limits what you see.
## Behaviour
- `graphType` is a comma-separated list of `heartRate` and `respiratoryRate`. Repeated entries are ignored. `startDate` must not be after `endDate`.
- Days are cut at the project's time zone (default `Europe/Berlin`). The chart for a day starts at 09:00 local time, so a night stays in one day.
- A range of two or more days is an over-day chart: one point per day, at 09:00 local time, starting the day after `startDate`. Each point is the day's mean from the pre-computed statistics, with batch readings filling nights that have none.
- A range of one day or less is an in-day chart: 30-second points across the 24 hours that start at 09:00 local time on `startDate`. `endDate` only decides which kind of chart you get. In-day points come from batch readings only.
- Before a night's recording is picked, both charts drop the readings and sleep statistics that end outside the resident's use periods of their device, as `GET /v1/slim/sleep/statistics` does. So a previous resident's night that ended before the device was handed over, but reached Ovok after it and was stored under this resident, is not charted. A resident with no device use history keeps all of them.
- Once a resident has any use period, this also drops the readings of a device with no period of theirs, and those from before a device's earliest period. A device assigned before use periods were recorded gets its first one on its next edit in Ovok, starting at the Device's last write before that edit, so its readings from before then are not charted. Each device whose readings in a request all drop is counted in the `sleep.device_use_device_dropped` metric and logged at most once a minute.
- The use periods are read on every uncached call. When Medplum answers that read with an error, the route answers `502` rather than chart a night it cannot check; when the request itself fails, the route fails with Medplum's status, or `500`.
- When a night (the calendar day its recordings end on, in the project's time zone) has several sleep recordings left, both charts show only the readings of the one whose sleep statistics were written last (latest `meta.lastUpdated`): its heart and respiratory rate statistics, matched by the recording's exact period, and its batch readings, matched by their start (below). That is the rule `GET /v1/slim/sleep/statistics` uses. A night with no sleep statistics goes by its heart and respiratory rate statistics' write times. A night with one recording left, a night with batch readings only, and a night none of whose readings belongs to the chosen recording are charted with all the readings left. Readings with no end time cannot be put on a night, so neither rule applies to them: they are always charted.
- Sleep statistics are read over the chart's range, which ends at 09:00 local time on its last day, so a recording that starts later that day is not weighed.
- A batch block is matched by its start, because Sleepiz ends one up to about ten minutes before its recording: it belongs to the recording that starts at the same instant and ends at or after it, at most 15 minutes later, the earliest such end when two recordings share the start. A batch block that starts at any other time belongs to no recording, so on a night with several recordings it is dropped: a chosen recording whose only heart rate reading is a batch block that starts after the recording shows no heart rate for that night, while its respiratory rate still shows.
- Every bucket is returned. A bucket without a reading has `data: null`. `pointTimestamp` and `pointTimestampRange` show which readings filled it.
- `maxThreshold`, `minThreshold`, `maxBaseLine` and `minBaseLine` are the values that applied at that time. They are left out when none apply, and when the threshold lookup fails the chart still returns without them.
- When a heart or breathing rate limit changed inside the range (a nurse's edit or a home-wide save), each point carries the limit in force at its own time, as Signals recorded it, so the lines step where the limit changed. Points after the last change carry the limits the limits screen shows. If Signals' change history cannot be read, every point carries the current limits.
- Devices are keyed `-`. A resident who changed device has one entry per device.
- A graph type with no data in the range comes back as `{}`. When nothing at all can be charted, both `heartRate` and `respiratoryRate` are `{}`.
- Results are cached for up to 60 seconds. A write to the resident's data invalidates the cache sooner.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/trends/graphs?patientId=c3499c27-2973-0a7f-807e-fb8676a92dcb&startDate=2026-09-01T00:00:00Z&endDate=2026-09-30T00:00:00Z&graphType=heartRate,respiratoryRate' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{
"heartRate": {
"Sleepiz-5f0c...": {
"dataPoints": [
{
"timestamp": "2026-09-02T07:00:00.000Z",
"timestampMs": 1788332400000,
"data": 72,
"maxThreshold": 100,
"minThreshold": 60,
"pointTimestamp": "2026-09-02T05:41:00.000Z"
}
],
"stats": { "average": 72, "max": 72, "min": 72, "total": 1 }
}
},
"respiratoryRate": {}
}
```
- [Get realtime trends graphs](/api/slim/trends/get-realtime-trends-graphs): Returns the resident's readings from Signals, one data point per reading, in the same shape as `GET /v1/slim/trends/graphs`. Use it for the live part of a chart, or to look at any day of the last 14.
**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Organization:read`, `Device:read`, `Patient:read` and `DocumentReference:read`.
**Scope:** the resident must be in the caller's project or one of its sub-projects (not its parent). A resident outside that scope answers `404`, the same as one that does not exist.
## Behaviour
- The chart covers exactly `[startTime, endTime]`. Unlike `/graphs`, it does not snap to monitoring days.
- Every reading in the window comes back as Signals recorded it, oldest first: one data point per reading, at the reading's own time, with its own value. Nothing is bucketed or averaged, and no empty points are added between readings, so a silent device shows as a stretch with no points. A reading with no numeric value comes back with `data: null`.
- The response grows with the device's cadence: a day of readings every 30 seconds is about 2,900 points per graph type.
- The readings are the resident's, whatever device they wear now: a resident whose device was unassigned or moved to someone else, or who was discharged, still gets every reading Signals holds for them in the window. A resident who takes over a device gets only the readings sent after they took it.
- Readings are charted under one key: the resident's most recently assigned device, keyed as on `/graphs`. A resident with no device now is charted under the device they wore last, so the key does not change when the device is taken away, and a resident who never wore one under `Patient/`. Signals readings carry no device, so a resident whose device changed inside the window shows one key here where `/graphs` shows one per device.
- Threshold and baseline values are the same as `/graphs`. `stats` are computed over every reading in the window.
- Every graph type in the table below can be charted. Only `heartRate` and `respiratoryRate` carry threshold and baseline values. Each point carries the limit in force at its own time, as on `/graphs`, so the lines step where a limit changed inside the window.
- `startTime` must not be after `endTime`, the window may span at most 24 hours, and `startTime` must not be more than 14 days ago. A request that breaks one of these fails validation.
- Readings are charted by when they were observed, or by when Signals stored them when no observed time exists. Late-arriving readings are included.
- A graph type with no readings in the window is `{}`.
- If Signals cannot be reached, does not answer within 12 seconds, or holds more readings than one request can page through, the route returns `503` with `error: "signals_unavailable"` and a `retryAfterSec` value, rather than a partial or empty chart.
- Results are cached for up to 15 seconds. Both request times are rounded down to that interval, and the readings returned are those of the rounded window, so a repeated poll can show a window up to 15 seconds old. A result over 128 KB (most full days) is not cached.
- A chart reads this once per page load. Each caller may make 20 requests a minute; past that the route returns `429` with `Retry-After`. When too many realtime reads are already running on the server, it returns `503` with `error: "signals_unavailable"` and `retryAfterSec` at once, before reading anything.
## Graph types
Each type charts every Signals reading recorded under one of its codes. The names are the dashboard telemetry's, so
pulse rate by pulse oximetry is `pulseRate` and never part of `heartRate`.
| `graphType` | Codes |
| ------------------------ | ---------------------------------------------------------------- |
| `heartRate` | `8867-4`, `43149-4` |
| `respiratoryRate` | `9279-1` |
| `oxygenSaturation` | `59408-5`, `2708-6` |
| `pulseRate` | `8889-8` (heart rate by pulse oximetry) |
| `perfusionIndex` | `61006-3`, `PI` (Kinderspitex's own vital code, not LOINC) |
| `bodyTemperature` | `8310-5` |
| `systolicBloodPressure` | `8480-6` |
| `diastolicBloodPressure` | `8462-4` |
| `heartRateVariability` | `80404-7` |
## Example cURL request
```bash
curl -X GET \
'https://api.sandbox.ovok.com/v1/slim/trends/realtime?patientId=c3499c27-2973-0a7f-807e-fb8676a92dcb&startTime=2026-01-01T12:00:00Z&endTime=2026-01-02T12:00:00Z&graphType=heartRate,respiratoryRate' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/User
- [Get terms and conditions consent](/api/slim/user/get-terms-and-conditions-consent): Returns whether the signed-in practitioner has accepted the current terms and conditions. Use it to decide whether to show the terms prompt.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read` and `Consent:search` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- `termsAndConditionsConsent` is `true` only when an acceptance is on file and either matches the currently published terms version or no version has been published yet.
- Publishing new terms turns it `false` for everyone until they accept again.
- The published version is the one of the root project of your project tree: a child project follows its parent's terms. Without one, the platform-wide version applies.
- `GET /v1/me/consent/legal` returns the same acceptance with its dates and terms link.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/user/terms-and-conditions-consent' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update terms and conditions consent](/api/slim/user/update-terms-and-conditions-consent): Accepts or withdraws the terms and conditions for the signed-in practitioner. Other consents are not changed.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read`, `Consent:search`, `Consent:create` and `Consent:update` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- `true` records acceptance of the currently published terms version. `false` withdraws it.
- The acceptance is also kept as a legal `Consent` in your project: accepting creates or re-activates it with a link to the terms page of your project's practitioner app; withdrawing revokes it with reason `withdrawn`.
- Repeating the same value writes nothing. The call is idempotent.
- The consent answers of `/v1/me/consent/*` are refreshed right away.
- Returns the resulting `termsAndConditionsConsent`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/user/terms-and-conditions-consent' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "termsAndConditionsConsent": true }'
```
- [Get all user consents](/api/slim/user/get-all-user-consents): Returns every consent of the signed-in practitioner in one response. Use it at sign-in to decide which consent prompts to show.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read` and `Consent:search` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- Both `medicalSettingsNotificationsConsent` and `termsAndConditionsConsent` are versioned. Each is `true` only when an acceptance is on file and either matches the currently published version of that consent or no version has been published yet.
- Publishing a new version of a consent turns it `false` for everyone until they accept again.
- The published version is the one of the root project of your project tree. Without one, the platform-wide version applies.
- A consent with no record reads `false`.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/user/consents' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
```json
{ "medicalSettingsNotificationsConsent": true, "termsAndConditionsConsent": false }
```
- [Update user consents](/api/slim/user/update-user-consents): Updates one or more consents of the signed-in practitioner. Use it to save the answers of a combined consent prompt.
**Auth:** Bearer token for a practitioner session (the profile must be a `Practitioner`). The caller's access policy must grant `Consent:read`, `Consent:search`, `Consent:create` and `Consent:update` (a project admin who holds no access policy skips this check).
**Scope:** The caller's practitioner profile in the caller's project (from the token).
## Behaviour
- Send at least one of `medicalSettingsNotificationsConsent` and `termsAndConditionsConsent`. Only the fields you send change.
- `true` records acceptance of the currently published version of that consent. `false` withdraws it.
- A `termsAndConditionsConsent` change also creates, re-activates or revokes the legal `Consent` read by `GET /v1/me/consent/legal`.
- All changes commit together or not at all. Repeating the same values writes nothing.
- The consent answers of `/v1/me/consent/*` are refreshed right away.
- The response always carries the resulting state of every consent.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/user/consents' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "medicalSettingsNotificationsConsent": true, "termsAndConditionsConsent": true }'
```
- [Send support message](/api/slim/user/send-support-message): Sends a support email on behalf of the signed-in user to the support address configured for this Ovok environment.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Patient:read`, `Patient:search`, `Device:read`, `Device:search`, `Observation:read` and `Observation:search` (a project admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Sends one email built from the `message`, `version` and `environment` you send.
- The email also carries details taken from your session, not from the body: your name, email, project name, profile type, access policy name and tenant code.
- Nothing else is written.
- Returns `true` once the email is sent.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/user/support' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "message": "The live view does not load.", "version": "1.8.0", "environment": "production" }'
```
- [Delete user](/api/slim/user/delete-user): Removes a practitioner from a project: deletes their membership and practitioner profile, and their user account when this was their last membership. Use it to offboard a team member.
**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `Practitioner:delete` (a project admin who holds no access policy skips this check).
**Scope:** The practitioner's project must be the caller's project (from the token) or a direct child of it.
## Behaviour
- `profileType` must be `Practitioner` and `profileId` a UUID.
- The membership, the practitioner and, when it has no other membership, the user are deleted together or not at all.
- The owner of the caller's own project cannot be deleted. The owner of a child project can.
- After the delete, an account-deletion email is sent to the user's email address, if they have one. A failed email does not fail the request.
- Returns `{ "success": true }`.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/user/Practitioner/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- Slim/Zones
- [List zones](/api/slim/zones/list-zones): Lists the zones of your project with their device counts. A zone is a FHIR `Organization`. Use it for a zone overview; use `GET /v1/slim/zones/{zoneId}` for one zone's locations.
**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 `Organization:search`, `Organization:read` and `Device:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- Counts are taken from the same rows as `GET /v1/slim/device/live`: only devices assigned to a resident are counted. `deviceCount` is the number of such devices in the zone; `activeDeviceCount` and `inactiveDeviceCount` split them by whether the device is currently active, as on the live view.
- Only zones with at least one counted device are listed. A zone with no assigned devices does not appear; `GET /v1/slim/zones/device-counts?includeEmpty=true` lists it.
- `search` keeps zones whose name contains the text, ignoring case.
- `sortBy`: `name` (default), `deviceCount`, `activeDeviceCount` or `inactiveDeviceCount`. `orderBy`: `ASC` (default) or `DESC`.
- Paging: `page` from 0, `count` from 1 to 100 (default 20). `total` is the number of zones after the search filter.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/zones?sortBy=deviceCount&orderBy=DESC&page=0&count=20' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get zone device counts](/api/slim/zones/get-zone-device-counts): Returns device counts per zone for your project, with project-wide totals. A zone is a FHIR `Organization`.
**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 `Organization:search`, `Organization:read`, `Device:search` and `Device:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The caller's project (from the token).
## Behaviour
- By default, `deviceCount` matches the rows `GET /v1/slim/device/live` returns for each zone: devices assigned to a resident.
- `all=true` counts every device in each zone, assigned or not, and ignores `effectiveSleepStatus`.
- `effectiveSleepStatus` (`disconnected`, `connected`, `awake`, `away`, `asleep`) counts only devices in that state. A device that is not active counts as `disconnected`.
- `includeUnassigned=true` also counts devices with no resident (unless `all=true` already does) and adds a bucket, with `organization` unset, for devices in no zone.
- `includeEmpty=true` keeps project zones that have no matching devices, with zero counts.
- For each zone, `assignedResidentDeviceCount` counts devices with a resident, and `activeDeviceCount` / `inactiveDeviceCount` split devices by whether they are currently active.
- Zones are sorted by `deviceCount`, highest first. `total` is the number of entries; the `total…Count` fields sum the per-zone counts.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/zones/device-counts?includeEmpty=true&includeUnassigned=true' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Get zone detail](/api/slim/zones/get-zone-detail): Returns one zone with all of its locations and the devices and residents assigned to each location. A zone is a FHIR `Organization`. Use it for a zone drill-down view.
**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 `Organization:read` and `Location:read` (an admin or super admin who holds no access policy skips this check).
**Scope:** The zone must belong to the caller's project (from the token), its parent project, or one of its sub-projects.
## Behaviour
- Returns every location whose managing organization is the zone; there is no paging.
- Each location carries `floor`, `room` and `bed` when set, and its `devices` and `residents`. Devices and residents are sorted by name in natural order (so "Bed 2" sorts before "Bed 10").
- A location with no devices has empty `devices` and `residents` lists.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/zones/c3499c27-2973-0a7f-807e-fb8676a92dcb' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create location in zone](/api/slim/zones/create-location-in-zone): Creates a location (a FHIR `Location`) inside a zone. The new location's managing organization is the zone.
**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 `Location:create` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The location is created in the caller's project (from the token). A super-admin caller may pass `?projectId=` to create it in that project instead; the project must exist. The zone must belong to the project in use, its parent project, or one of its sub-projects.
## Behaviour
- `name` is required and must be unique among the locations your token can search.
- `floor`, `room` and `bed` are optional. When at least one is set, no other location in the zone may have the same floor, room and bed. A location with none of them is checked by name only.
- The location is created with no devices or residents. Assign them with `PUT /v1/slim/zones/{zoneId}/locations/{locationId}`.
- A location-created entry is added to the change history. A failure to write that entry does not fail the request.
- The response is the new location, in the same shape as `GET /v1/slim/location/{id}`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/zones/c3499c27-2973-0a7f-807e-fb8676a92dcb/locations' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Room 101 Bed 1",
"floor": "1",
"room": "101",
"bed": "1"
}'
```
- [Delete location in zone](/api/slim/zones/delete-location-in-zone): Deletes an empty location from a zone, or, with `dryRun=true`, previews which devices and residents are at it without changing anything.
**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 `Location:update` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The zone must belong to the caller's project (from the token), its parent project, or one of its sub-projects. The location must belong to the zone and to your project or a sub-project; a parent project's location is refused.
## Behaviour
- `dryRun=true` returns `200` with `affected_devices` and `affected_residents` at the location, and a `warning` when either list is not empty. Nothing is written.
- Without `dryRun` (any other value counts as false), the location is deleted only when no device is assigned to it. The call answers `204` with no body.
- Reassign the location's devices before deleting it; the delete never unassigns devices for you.
- A location-deleted entry is added to the change history. A failure to write that entry does not fail the request.
## Example
```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/zones/c3499c27-2973-0a7f-807e-fb8676a92dcb/locations/87ea5dfc-8b8e-384d-8489-79496e706390?dryRun=true' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Update location in zone](/api/slim/zones/update-location-in-zone): Updates a location in a zone: its name, floor, room and bed, the devices assigned to it, and the resident on those devices.
**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 `Location:update` and `Device:update` (an admin or super admin who holds no access policy skips this check).
**Scope:** The zone must belong to the caller's project (from the token), its parent project, or one of its sub-projects. The location must be in the caller's project, and its managing organization must be the zone. Devices and residents named in the body must be in your project or a sub-project.
## Behaviour
- `name` is required and must be unique among the locations your token can search, not counting this one.
- `floor`, `room` and `bed` replace only the values you send; omitted ones keep their stored value. The resulting floor, room and bed must not match another location in the zone.
- `deviceId` (one UUID or a list) sets the devices at the location to exactly that set: devices not listed are removed from it, new ones are added. `null` removes every device. Omit `deviceId` to leave the devices unchanged.
- `patientId` assigns that resident to the devices named in `deviceId`, or, without `deviceId`, to the location's single device. A resident assigned there before is unassigned from those devices.
- **Omitting `patientId` unassigns the current resident from every device at the location** (and from the devices in `deviceId`). Send the current `patientId` to keep the resident.
- A discharged resident cannot be assigned.
- The write is atomic and takes a short write lock on the devices and locations it touches.
- The response is the updated location, in the same shape as `GET /v1/slim/location/{id}`.
## Example
```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/zones/c3499c27-2973-0a7f-807e-fb8676a92dcb/locations/87ea5dfc-8b8e-384d-8489-79496e706390' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{
"name": "Room 101 Bed 1",
"room": "101",
"bed": "1",
"deviceId": "c3499c27-2973-0a7f-807e-fb8676a92dcb",
"patientId": "87ea5dfc-8b8e-384d-8489-79496e706390"
}'
```
- Sub Project
- [Check child project access policy drift](/api/sub-project/check-child-project-access-policy-drift): Compares the AccessPolicies of each direct child of your current project with your project's own, and reports the differences. Nothing is written.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not compared.
## Behaviour
- Policies are matched by `name`, and compared on `compartment`, `resource` and `ipAccessRule`.
- Each difference is one `drift` entry with a `kind`:
- `missing`: the child has no policy with that name.
- `changed`: the child's policy differs from yours.
- `orphan`: the child holds a policy whose name your project does not have. A child's own policies, such as its patient-sharing template, show up as orphans.
- `copyOfDeletedPolicy` is true for an `orphan` that is a copy of one of your policies you have since deleted: every copy is tagged with the id of the policy it copies, and that policy is no longer in your project. It is false for every other entry, a child's own policies included, and always false for the two patient-sharing templates every project makes for itself, whatever their tag.
- `count` is the number of entries.
- `POST access-policy/reconcile` repairs the `missing` and `changed` entries and deletes the `copyOfDeletedPolicy` ones.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/drift' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Check child project access policy drift](/api/sub-project/check-child-project-access-policy-drift-2): Compares the AccessPolicies of each direct child of your current project with your project's own, and reports the differences. Nothing is written.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not compared.
## Behaviour
- Policies are matched by `name`, and compared on `compartment`, `resource` and `ipAccessRule`.
- Each difference is one `drift` entry with a `kind`:
- `missing`: the child has no policy with that name.
- `changed`: the child's policy differs from yours.
- `orphan`: the child holds a policy whose name your project does not have. A child's own policies, such as its patient-sharing template, show up as orphans.
- `copyOfDeletedPolicy` is true for an `orphan` that is a copy of one of your policies you have since deleted: every copy is tagged with the id of the policy it copies, and that policy is no longer in your project. It is false for every other entry, a child's own policies included, and always false for the two patient-sharing templates every project makes for itself, whatever their tag.
- `count` is the number of entries.
- `POST access-policy/reconcile` repairs the `missing` and `changed` entries and deletes the `copyOfDeletedPolicy` ones.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/drift' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Check child project access policy drift](/api/sub-project/check-child-project-access-policy-drift-3): Compares the AccessPolicies of each direct child of your current project with your project's own, and reports the differences. Nothing is written.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not compared.
## Behaviour
- Policies are matched by `name`, and compared on `compartment`, `resource` and `ipAccessRule`.
- Each difference is one `drift` entry with a `kind`:
- `missing`: the child has no policy with that name.
- `changed`: the child's policy differs from yours.
- `orphan`: the child holds a policy whose name your project does not have. A child's own policies, such as its patient-sharing template, show up as orphans.
- `copyOfDeletedPolicy` is true for an `orphan` that is a copy of one of your policies you have since deleted: every copy is tagged with the id of the policy it copies, and that policy is no longer in your project. It is false for every other entry, a child's own policies included, and always false for the two patient-sharing templates every project makes for itself, whatever their tag.
- `count` is the number of entries.
- `POST access-policy/reconcile` repairs the `missing` and `changed` entries and deletes the `copyOfDeletedPolicy` ones.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/drift' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Check child project access policy drift](/api/sub-project/check-child-project-access-policy-drift-4): Compares the AccessPolicies of each direct child of your current project with your project's own, and reports the differences. Nothing is written.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not compared.
## Behaviour
- Policies are matched by `name`, and compared on `compartment`, `resource` and `ipAccessRule`.
- Each difference is one `drift` entry with a `kind`:
- `missing`: the child has no policy with that name.
- `changed`: the child's policy differs from yours.
- `orphan`: the child holds a policy whose name your project does not have. A child's own policies, such as its patient-sharing template, show up as orphans.
- `copyOfDeletedPolicy` is true for an `orphan` that is a copy of one of your policies you have since deleted: every copy is tagged with the id of the policy it copies, and that policy is no longer in your project. It is false for every other entry, a child's own policies included, and always false for the two patient-sharing templates every project makes for itself, whatever their tag.
- `count` is the number of entries.
- `POST access-policy/reconcile` repairs the `missing` and `changed` entries and deletes the `copyOfDeletedPolicy` ones.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/drift' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Repair child project access policy drift](/api/sub-project/repair-child-project-access-policy-drift): Repairs AccessPolicy drift in the direct children of your current project: it creates each missing copy and overwrites each changed one from your project's policy.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not touched.
## Behaviour
- Uses the same comparison as `GET access-policy/drift` and returns what it found, in the same shape, before the repair.
- A `missing` policy is created in the child; a `changed` one is overwritten with your `compartment`, `resource` and `ipAccessRule`. Either way the child's copy is tagged with the id of your policy.
- An `orphan` with `copyOfDeletedPolicy: true` is deleted: it is a copy of a policy you have deleted. Members of the child who still hold it are locked out of the child until they are given another role.
- Any other `orphan` is listed and never deleted. A child's own policies carry no copy tag, and its patient-sharing templates are never deleted, whatever their tag.
- Idempotent: a second call finds nothing left to repair, apart from the orphans it keeps.
- The writes are not atomic. If one fails, the request fails; policies already written stay written, and you can call the route again.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/reconcile' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Repair child project access policy drift](/api/sub-project/repair-child-project-access-policy-drift-2): Repairs AccessPolicy drift in the direct children of your current project: it creates each missing copy and overwrites each changed one from your project's policy.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not touched.
## Behaviour
- Uses the same comparison as `GET access-policy/drift` and returns what it found, in the same shape, before the repair.
- A `missing` policy is created in the child; a `changed` one is overwritten with your `compartment`, `resource` and `ipAccessRule`. Either way the child's copy is tagged with the id of your policy.
- An `orphan` with `copyOfDeletedPolicy: true` is deleted: it is a copy of a policy you have deleted. Members of the child who still hold it are locked out of the child until they are given another role.
- Any other `orphan` is listed and never deleted. A child's own policies carry no copy tag, and its patient-sharing templates are never deleted, whatever their tag.
- Idempotent: a second call finds nothing left to repair, apart from the orphans it keeps.
- The writes are not atomic. If one fails, the request fails; policies already written stay written, and you can call the route again.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/reconcile' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Repair child project access policy drift](/api/sub-project/repair-child-project-access-policy-drift-3): Repairs AccessPolicy drift in the direct children of your current project: it creates each missing copy and overwrites each changed one from your project's policy.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not touched.
## Behaviour
- Uses the same comparison as `GET access-policy/drift` and returns what it found, in the same shape, before the repair.
- A `missing` policy is created in the child; a `changed` one is overwritten with your `compartment`, `resource` and `ipAccessRule`. Either way the child's copy is tagged with the id of your policy.
- An `orphan` with `copyOfDeletedPolicy: true` is deleted: it is a copy of a policy you have deleted. Members of the child who still hold it are locked out of the child until they are given another role.
- Any other `orphan` is listed and never deleted. A child's own policies carry no copy tag, and its patient-sharing templates are never deleted, whatever their tag.
- Idempotent: a second call finds nothing left to repair, apart from the orphans it keeps.
- The writes are not atomic. If one fails, the request fails; policies already written stay written, and you can call the route again.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/reconcile' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Repair child project access policy drift](/api/sub-project/repair-child-project-access-policy-drift-4): Repairs AccessPolicy drift in the direct children of your current project: it creates each missing copy and overwrites each changed one from your project's policy.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token) and its direct children. Grandchildren are not touched.
## Behaviour
- Uses the same comparison as `GET access-policy/drift` and returns what it found, in the same shape, before the repair.
- A `missing` policy is created in the child; a `changed` one is overwritten with your `compartment`, `resource` and `ipAccessRule`. Either way the child's copy is tagged with the id of your policy.
- An `orphan` with `copyOfDeletedPolicy: true` is deleted: it is a copy of a policy you have deleted. Members of the child who still hold it are locked out of the child until they are given another role.
- Any other `orphan` is listed and never deleted. A child's own policies carry no copy tag, and its patient-sharing templates are never deleted, whatever their tag.
- Idempotent: a second call finds nothing left to repair, apart from the orphans it keeps.
- The writes are not atomic. If one fails, the request fails; policies already written stay written, and you can call the route again.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/internal/sub-project/access-policy/reconcile' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [List project relationships](/api/sub-project/list-project-relationships): Returns where your current project sits in the project hierarchy: its parent and its direct children.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token).
## Behaviour
- `parentProjectId` is `null` for a project with no parent.
- `subProjectIds` lists direct children only.
- The result is cached for up to 5 minutes. Creating or deleting a child through Ovok clears the cache; other changes can take that long to show.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/internal/sub-project' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create a sub tenant](/api/sub-project/create-a-sub-tenant): Creates a child project (sub-tenant) of your current project. Use it from admin tooling and from headless integrations that hold an admin client token.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`). Setting `parentProjectId` also requires a super admin.
**Scope:** the parent is the caller's project (from the token), or `parentProjectId` for a super admin.
## Behaviour
- Creates, all or nothing: the `Project` (with the standard Ovok project features, `extension` copied as given, and its own Signals tenant), its tenant code, the parent's link to it, a Practitioner and an admin membership in the new project, and the parent-child relationship. If a step fails, the steps already done are undone.
- **User session:** the new project is owned by your user, the Practitioner copies your profile, and the membership is yours. The response is `{ "success": true }`.
- **Client application session** (no user): the new project is owned by the parent project. The response is `{ "success": true, "projectId": "..." }`.
- A concurrent create of the same name under the same parent is refused with 409 and writes nothing. A later create with the same name makes a second project.
- Served at both `/v1/internal/sub-project` and `/sub-project`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/internal/sub-project' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "name": "My Medical Project" }'
```
- [List project relationships](/api/sub-project/list-project-relationships-2): Returns where your current project sits in the project hierarchy: its parent and its direct children.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token).
## Behaviour
- `parentProjectId` is `null` for a project with no parent.
- `subProjectIds` lists direct children only.
- The result is cached for up to 5 minutes. Creating or deleting a child through Ovok clears the cache; other changes can take that long to show.
## Example
```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/internal/sub-project' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```
- [Create a sub tenant](/api/sub-project/create-a-sub-tenant-2): Creates a child project (sub-tenant) of your current project. Use it from admin tooling and from headless integrations that hold an admin client token.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`). Setting `parentProjectId` also requires a super admin.
**Scope:** the parent is the caller's project (from the token), or `parentProjectId` for a super admin.
## Behaviour
- Creates, all or nothing: the `Project` (with the standard Ovok project features, `extension` copied as given, and its own Signals tenant), its tenant code, the parent's link to it, a Practitioner and an admin membership in the new project, and the parent-child relationship. If a step fails, the steps already done are undone.
- **User session:** the new project is owned by your user, the Practitioner copies your profile, and the membership is yours. The response is `{ "success": true }`.
- **Client application session** (no user): the new project is owned by the parent project. The response is `{ "success": true, "projectId": "..." }`.
- A concurrent create of the same name under the same parent is refused with 409 and writes nothing. A later create with the same name makes a second project.
- Served at both `/v1/internal/sub-project` and `/sub-project`.
## Example
```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/internal/sub-project' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
-H 'Content-Type: application/json' \
-d '{ "name": "My Medical Project" }'
```
- [List project relationships](/api/sub-project/list-project-relationships-3): Returns where your current project sits in the project hierarchy: its parent and its direct children.
**Auth:** bearer token of a project admin (`ProjectMembership.admin`).
**Scope:** the caller's project (from the token).
## Behaviour
- `parentProjectId` is `null` for a project with no parent.
- `sub