Devices API

Base path: /api/devices (device groups use /api/device-groups)

All endpoints require authentication. See API Overview for auth details.

Tip

For device management, use the Devices page in the Snippbot UI.

Devices

List devices

GET /api/devices

Query parameters: status (approved, pending, blocked, revoked), limit, offset

Response:

{
  "devices": [
    {
      "id": "device_abc123",
      "name": "build-server",
      "platform": "Linux",
      "architecture": "x86_64",
      "os_version": "Ubuntu 22.04",
      "agent_version": "0.1.5",
      "status": "approved",
      "online": true,
      "last_seen_at": "2026-03-02T14:00:00Z",
      "capabilities": ["bash", "filesystem", "system_info"],
      "paired_at": "2026-01-15T00:00:00Z"
    }
  ],
  "total": 4
}

Get device details

GET /api/devices/{id}

Returns full device info including health metrics and execution history.

Generate a pairing code

POST /api/devices/pair

Response:

{
  "code": "847291",
  "expires_at": "2026-03-02T14:05:00Z",
  "qr_url": "/api/devices/pair/qr"
}

The code is valid for 5 minutes. On the remote machine:

snippbot-device pair --host DAEMON_IP --code 847291

Claim a pairing code

POST /api/devices/pair/claim

Used by the device agent to claim a pairing code and complete the handshake.

Approve a device

POST /api/devices/{id}/approve

Required if auto-approve is disabled. Changes status from pending to approved.

Block a device

POST /api/devices/{id}/block

Blocks the device — existing WebSocket connection is terminated, no new connections allowed.

Revoke a device token

POST /api/devices/{id}/revoke-token

Revokes the device auth token. The device must re-pair to reconnect.

Delete a device

DELETE /api/devices/{id}

Permanently removes the device record.

Device health

GET /api/devices/{id}/health

Response:

{
  "cpu_percent": 12.5,
  "memory_percent": 45.2,
  "disk_percent": 38.1,
  "load_average": [0.45, 0.38, 0.32],
  "uptime_seconds": 432000,
  "network": {
    "bytes_sent": 1048576,
    "bytes_recv": 2097152
  },
  "timestamp": "2026-03-02T14:00:00Z"
}

Remote execution

Execute a tool on a device

POST /api/devices/{id}/execute

{
  "tool": "bash",
  "args": {"command": "uptime && df -h"},
  "timeout": 60
}

Response:

{
  "execution_id": "exec_abc123",
  "device_id": "device_abc123",
  "tool": "bash",
  "status": "completed",
  "output": "14:32:01 up 5 days...\nFilesystem...",
  "error": null,
  "duration_ms": 234
}

List executions for a device

GET /api/devices/{id}/executions

Query: limit, offset

Response includes recent tool calls with their status, output, and timing.

Additional device endpoints

The following endpoints also exist but are not documented in full here:

Method	Path	Description
PATCH	/api/devices/{id}	Update device metadata
GET	/api/devices/{id}/capabilities	Get device capabilities
GET	/api/devices/{id}/queue	Get command queue
DELETE	/api/devices/{id}/queue	Clear command queue
DELETE	/api/devices/{id}/queue/{command_id}	Cancel queued command
GET	/api/devices/{id}/transfers	Get file transfers
POST	/api/devices/{id}/remote/start	Start remote session
POST	/api/devices/{id}/remote/stop	Stop remote session
GET	/api/devices/routing	Get routing config
GET	/api/devices/routing/explain	Explain routing decisions
PUT	/api/devices/routing/preferences/{tool}	Set routing preference
DELETE	/api/devices/routing/preferences/{tool}	Clear routing preference

Device groups

Device groups use a separate base path: /api/device-groups.

List groups

GET /api/device-groups

Create a group

POST /api/device-groups

{
  "name": "Office Machines"
}

Get a group

GET /api/device-groups/{id}

Delete a group

DELETE /api/device-groups/{id}

Add a device to a group

POST /api/device-groups/{id}/members/{device_id}

Remove a device from a group

DELETE /api/device-groups/{id}/members/{device_id}

Execute on a group

POST /api/device-groups/{id}/execute

Runs the tool on all online devices in the group.

{
  "tool": "bash",
  "args": {"command": "apt-get update -qq"},
  "timeout": 300
}

Note

Group membership is managed by adding/removing individual devices via POST /api/device-groups/{id}/members/{device_id} and DELETE /api/device-groups/{id}/members/{device_id}. There is no PATCH endpoint for bulk-updating group membership.

WebSocket connection

The device agent connects via WebSocket:

ws://DAEMON_IP:18781/device/ws?token=DEVICE_TOKEN

Messages follow the JSON-RPC format. This is the internal protocol used by snippbot-device — you generally don’t need to implement this yourself.