Devices API

These endpoints list the device groups and configurations a session can request. Authentication, error shapes and rate limits are covered in the REST API overview.

List Devices

List devices registered with the platform. Only devices currently available or busy are returned.

GET /api/v1/devices/

Auth: Bearer token required.

Query parameters:

Response:

[
  {
    "id": 1,
    "device_id": "ABCD1234-...",
    "worker_id": "worker-1",
    "name": "iPhone 16",
    "type": "ios",
    "category": "phone",
    "os_version": "18.0",
    "status": "available"
  }
]

device_id is the value to pass as specific_device_id when creating a session, or as device_id on the CI run endpoints.

List Device Pools

Grouped view of the device list: one entry per (model, OS version, platform, category) combination, with availability counts. This is what the session-start device picker uses.

GET /api/v1/devices/pools

Auth: Bearer token required.

Response:

[
  {
    "group_key": "ios|phone|iPhone 16|18.0",
    "model": "iPhone 16",
    "os_version": "18.0",
    "device_type": "ios",
    "category": "phone",
    "total": 4,
    "free": 3
  }
]

Groups whose devices are all currently unreachable are omitted; they reappear when capacity returns.

Get Device

GET /api/v1/devices/{device_id}

Auth: Bearer token required.

device_id is the string device identifier (the device_id field from the list response, not the numeric id).

Response: A single device object (same shape as the list entries).

Errors:

• 404 — Device not found.