List devices

GET

/api/v1/devices

const url = 'http://localhost:3000/api/v1/devices?limit=20&offset=0&cursor=eyJpZCI6IjEyMzQifQ%3D%3D&status=ONLINE&environment=production&region=us-west';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/devices?limit=20&offset=0&cursor=eyJpZCI6IjEyMzQifQ%3D%3D&status=ONLINE&environment=production&region=us-west' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves a paginated list of devices with optional filtering by status and labels.

Authorizations

api-key
bearer

Parameters

Query Parameters

limit

number

default: 20 >= 1 <= 100

Example

Maximum number of devices to return

offset

number

Example

Number of devices to skip for pagination

cursor

string

Example

eyJpZCI6IjEyMzQifQ==

Cursor for cursor-based pagination (alternative to offset)

status

string

Allowed values: ONLINE OFFLINE PENDING ERROR

Example

ONLINE

Filter by device status

labels

Filter by device labels (JSON object)

object

key

additional properties

string

Example

{
  "environment": "production",
  "region": "us-west"
}

Responses

200

List of devices retrieved successfully

application/json

object

data

required

Array of device objects

Array<object>

object

required

Unique device identifier (UUID)

string format: uuid

clientId

required

Client-provided device identifier

string

name

Human-readable device name

string

status

required

Current device status

string

Allowed values: ONLINE OFFLINE PENDING ERROR

capabilities

required

Device capabilities as reported during onboarding

object

key

additional properties

any

labels

required

Key-value labels for device organization and filtering

object

key

additional properties

string

lastSeenAt

Timestamp of last communication from device

string format: date-time

createdAt

required

Timestamp when device was registered

string format: date-time

updatedAt

required

Timestamp of last device update

string format: date-time

total

required

Total number of devices matching the filter criteria

number

hasMore

required

Indicates if there are more devices available

boolean

nextCursor

Cursor for fetching the next page of results

string

Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "clientId": "edge-device-001",
      "name": "Production Edge Gateway 1",
      "status": "ONLINE",
      "capabilities": {
        "cpu": {
          "cores": 4,
          "architecture": "arm64"
        },
        "memory": {
          "total": 8192
        },
        "containers": {
          "runtime": "containerd"
        }
      },
      "labels": {
        "environment": "production",
        "region": "us-west",
        "tier": "edge"
      },
      "lastSeenAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "hasMore": true,
  "nextCursor": "eyJpZCI6IjEyMzQifQ=="
}

401

Unauthorized - Invalid or missing authentication

403

Forbidden - Insufficient permissions