Read devices and agent versions

Enable Read → Devices (READ_DEVICES) on an API service key. Existing keys need the permission added explicitly. Oneleet Agent must be enabled for the workspace. This permission grants device reads, including device details and compliance status; it does not grant device updates or commands.

Use these existing REST endpoints:

GET /api/v1/tenants/{tenant}/tenant-devices
GET /api/v1/tenant-devices/{tenant-device}

The corresponding MCP tools are TenantDeviceList and TenantDeviceGet. Use agentInfo.agentVersion for the reported agent version and agentInfo.lastPing for the recorded contact time. Unreported values may be absent. Neither field establishes whether auto-update is working.

Service-key and OAuth lists default to 25 devices. Pass limit (1–100) and follow nextCursor as cursor with the same workspace until nextCursor is absent. Pages include archived devices and are ordered by workspace device ID. This is a live listing; changes during pagination may affect later pages.

curl --fail-with-body \
  -H "Authorization: Bearer $ONELEET_API_TOKEN" \
  "https://api.oneleet.com/api/v1/tenants/$ONELEET_TENANT_ID/tenant-devices?limit=25"

For MCP, the workspace is inferred from the connection; an explicit tenant must match it. TenantDeviceGet takes tenant-device, the id from a list row. MCP tool results are limited to 1 MiB; request smaller pages if needed. These read tools return JSON to the client.

OAuth connections require the corresponding READ_DEVICES permission configured and granted by the authorization server, plus fresh consent. The signed-in user’s normal workspace permissions still apply. Under the standard roles, members can list and export devices; device detail reads require an administrator or auditor role.

Download a bulk export

Call TenantDeviceListExport in MCP, or GET /api/v1/tenants/{tenant}/tenant-devices/export, with the same READ_DEVICES permission as the device list. The file is prepared in the background. The call waits up to 15 seconds for it (wait sets a different number of seconds, up to 25) and then answers with the export’s status. While the status is PENDING or RUNNING, call again until it is COMPLETED; the response then carries downloadUrl, fileName, and recordCount. Download the file from downloadUrl within one hour. Anyone with that link can access it until it expires. A completed export is reused for an hour, so repeated calls return the same file rather than building it again. A FAILED export without a failureReason is retried by the next call; one with a failureReason cannot succeed as requested.

The gzip-compressed JSON Lines file contains one TenantDevice per line, with the same device details, agent info, and compliance status as the device list, including archived devices. Raw agent reports and logs aren’t included. The export reads live pages, not a point-in-time snapshot. Stored exports follow a 90-day cleanup policy.

Save the file directly for local analysis, keeping its contents out of the assistant’s context. For example, after saving it as oneleet-devices.jsonl.gz:

import gzip
import json

with gzip.open("oneleet-devices.jsonl.gz", "rt") as devices:
    for line in devices:
        device = json.loads(line)
        print(device["name"], device.get("agentInfo", {}).get("agentVersion"))