Audit

List change history

List change history using Ovok’s Slim API.

MethodPath
GET/v1/slim/change-history

Authentication · Access policies

Lists the recorded changes to thresholds, locations, zones, devices, residents, users and roles in your project. Use it for the resident and administration change-history screens.

Access rows cover users invited (userInvited), renamed (userRenamed), moved to another role (userRoleChanged) or removed (userRemoved), and roles created (roleCreated), given other permissions (rolePermissionsChanged) or deleted (roleDeleted). Users and roles are named by name; Access rows do not involve a resident.

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.

Request

Query parameters

Unknown query parameters are ignored.

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 50, minimum 1, maximum 100.
types"Threshold" | "Location" | "Zone" | "Device" | "Resident" | "Access"NoKeep only these change types. Repeat the parameter to pass several. Omit for all types.
scope"all" | "global"Noall returns every row. global keeps only project-wide changes. Default all.
userIdstringNoOne or more user ids, repeated or comma-separated. Every value must be an id.
residentIdstringNoOne or more resident ids, repeated or comma-separated. Every value must be an id.
deviceIdstringNoOne or more device ids, repeated or comma-separated. Every value must be an id.
locationIdstringNoOne or more location ids, repeated or comma-separated. Every value must be an id.
zoneIdstringNoOne or more zone ids, repeated or comma-separated. Every value must be an id.
relatedTostringNoOne or more typed references (Patient/<id>, Device/<id>, Location/<id> or Organization/<id>), repeated or comma-separated.
actionsstringNoOne or more of created, deleted, renamed, moved, assigned, unassigned, discharged, reactivated or thresholdChanged. Rows recorded before this filter shipped have no action and never match.
sort"asc" | "desc"NoRecording-time order. Default desc.
startDatestring (ISO 8601 date-time)NoOnly changes recorded at or after this time. Default: 30 days before now.
endDatestring (ISO 8601 date-time)NoOnly changes recorded at or before this time.

Behaviour

  • Each row is one recorded change. details.key names the change and details.values holds the values to put into its message. See the change-history key catalogue for the keys and their values.
  • Rows are sorted by recording time, newest first by default. Use sort=asc for oldest first. Rows with the same millisecond always keep a fixed order, so paging does not skip or repeat 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 project-wide changes, including organization threshold edits, device, location and zone lifecycle changes, and Access changes to users and roles. scope=all (the default) returns every row.
  • Each id filter accepts one or more ids, repeated or comma-separated. Values within one filter are ORed; different filters are combined with AND. userId matches the practitioner who made the change.
  • relatedTo matches a row once if it concerns any named resource. Use actions to filter by change kind. Older rows without an action never match actions.
  • Changes a device makes itself, such as a baseline re-push after a new 7-day mean, are never listed or counted.
  • 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

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/change-history?page=0&count=50' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Change history rows retrieved successfully.

{
  "total": 2,
  "page": 0,
  "count": 50,
  "resources": [
    {
      "id": "6e1f3a9c-2b7d-4c58-8a40-d3b9e5f17c26",
      "type": "Device",
      "user": "Alex Example",
      "residentId": "demo-resident",
      "resident": { "patientId": "6e4f3a20-1b8c-4d7e-a2f1-5c9b0d3e6f18", "residentId": "demo-resident" },
      "deviceId": "Demo/1000001",
      "locationId": null,
      "zoneId": null,
      "time": "2026-10-09T07:45:12.000Z",
      "details": {
        "key": "residentDeviceAssigned",
        "values": { "resident": "demo-resident", "deviceId": "Demo/1000001" }
      }
    },
    {
      "id": "1d8a2f60-3b5c-4e79-9a01-6c2d8f4b7e35",
      "type": "Access",
      "user": "Alex Example",
      "residentId": "",
      "resident": null,
      "deviceId": "",
      "locationId": null,
      "zoneId": null,
      "time": "2026-10-09T07:45:11.000Z",
      "details": {
        "key": "userRoleChanged",
        "values": { "user": "Alex Example", "fromRole": "Nurse", "toRole": "Admin" }
      }
    }
  ]
}
FieldTypeDescription
totalintegerNumber of rows the list can return across all pages. Never more than 10,000.
pageintegerPage number of this response.
countintegerPage size you asked for. The page can hold fewer rows.
resourcesobject[]The rows of this page in the order selected by sort.
resources[].idstringId of the change record.
resources[].type"Threshold" | "Location" | "Zone" | "Device" | "Resident" | "Access"Change type.
resources[].userstringDisplay name of the person who made the change. Empty string when there is none.
resources[].residentIdstringThe affected resident's Resident ID, or an empty string. It is never a name or an internal patient id.
resources[].residentobject | null{ patientId, residentId }, or null when no resident is involved. residentId is the Resident ID, or null when the resident has none; it is never a name.
resources[].deviceIdstringThe affected device's name, not the device id. The device id for old rows that have no name. Empty string when no device is involved.
resources[].locationIdstring | nullName of the room the change is about. For a move, the room the resident left. null when there is none.
resources[].zoneIdstring | nullName of the zone the change is about. For a move, the zone the resident left. null when there is none.
resources[].timestring (ISO 8601 date-time)When the change was recorded.
resources[].detailsobjectWhat changed, as a message key and its values.
resources[].details.keystringMessage key, such as residentDeviceAssigned. genericMessage for old rows that carry plain text.
resources[].details.valuesobjectValues for the message, keyed by name. Each value is a string, a number or null. Left out when the message has none. For genericMessage it holds message.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, or you lack Provenance:read.
422A value in an id filter is not an id, relatedTo is invalid, actions contains an unknown value, or another query parameter fails validation.

Last updated on

On this page