Devices

List devices

List devices using Ovok’s Slim API.

MethodPath
GET/v1/slim/device

Authentication · Access policies

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).

Request

Query parameters

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
sortBy"deviceName" | "locationName" | "patientName" | "organizationName" | "lastActivityTime" | "createdAt"NoSort column. Default deviceName.
orderBy"ASC" | "DESC"NoSort direction. Upper case only. Default ASC.
searchstringNoCase-insensitive substring match on device name, location name and zone name. Trimmed, at least 1 character.
patientSearchstringNoCase-insensitive substring match on resident name. Trimmed, at least 1 character.
organizationIdstringNoKeep devices in this zone.
locationIdstringNoKeep devices in this location.
patientIdstringNoKeep the device of this resident.
activebooleanNotrue keeps active devices. Any other value keeps inactive devices. Omit to keep both.

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.
  • 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

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device?page=0&count=20&sortBy=deviceName&orderBy=ASC' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — One page of devices.

{
  "total": 1,
  "page": 0,
  "count": 20,
  "resources": [
    {
      "id": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "name": "Demo/1000001",
      "thingsboardId": "Demo/1000001",
      "status": "active",
      "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
      "organizationName": "Zone A",
      "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
      "locationName": "Room 101 Bed 1",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
      "patientName": "demo-resident",
      "lastActivityTime": "2026-10-09T08:53:20.000Z",
      "createdAt": "2026-09-01T07:30:00.000Z"
    }
  ]
}
FieldTypeDescription
totalintegerNumber of rows after filtering, across all pages.
pageintegerPage number of this response.
countintegerPage size of this response.
resourcesobject[]The devices of this page.
resources[].idstring (uuid)Device id.
resources[].namestringDevice name.
resources[].thingsboardIdstringDevice identifier that telemetry is keyed by.
resources[].status"active" | "inactive"active when the device's live telemetry reports it active.
resources[].organizationIdstring | nullZone id.
resources[].organizationNamestring | nullZone name.
resources[].locationIdstring | nullLocation id.
resources[].locationNamestring | nullLocation name.
resources[].patientIdstring | nullResident on the device.
resources[].patientNamestring | nullThe resident's full display name.
resources[].lastActivityTimestring | nullLatest telemetry activity time, or the device's last-seen time when telemetry has none. ISO 8601.
resources[].createdAtstring | nullWhen the device record was last changed, as an ISO 8601 time string.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, you lack Device:search or Device:read, your session has no project, or you cannot access the project.
422A query parameter fails validation.
503The device list cannot be built and no earlier complete list exists. Retry shortly.

Last updated on

On this page