Download OpenAPI specification:
Manage IoT devices registered with the SmartTouch Cloud Platform.
The Device API lets you list, inspect, update, and deregister devices. A device is automatically registered the first time its Remote Access Agent connects to the session broker using a valid TLS certificate.
Returns all devices visible to the authenticated user. Supports filtering by agent status and fleet label.
| status | string Enum: "online" "offline" "unknown" Filter devices by agent status |
| fleet | string Example: fleet=factory-floor Filter devices by fleet label |
| page | integer >= 1 Default: 1 Page number (1-based) |
| per_page | integer [ 1 .. 200 ] Default: 50 Number of results per page |
{- "status": 200,
- "data": [
- {
- "id": "sensor-001",
- "display_name": "Temperature Sensor 001",
- "fleet": "factory-floor",
- "agent_status": "online",
- "agent_version": "1.4.2",
- "last_seen_at": "2026-06-08T09:12:00Z",
- "certificate": {
- "subject": "CN=sensor-001,OU=remote-access,O=smarttouch",
- "expires_at": "2027-06-08T00:00:00Z"
}
}, - {
- "id": "sensor-002",
- "display_name": "Humidity Sensor 002",
- "fleet": "factory-floor",
- "agent_status": "offline",
- "agent_version": "1.4.1",
- "last_seen_at": "2026-06-08T06:00:00Z",
- "certificate": {
- "subject": "CN=sensor-002,OU=remote-access,O=smarttouch",
- "expires_at": "2027-06-08T00:00:00Z"
}
}
], - "meta": {
- "page": 1,
- "per_page": 50,
- "total": 2
}
}Returns full details for a single device, including certificate metadata and remote access configuration.
| deviceId required | string Example: sensor-001 Unique device identifier (e.g., |
{- "status": 200,
- "data": {
- "id": "sensor-001",
- "display_name": "Temperature Sensor 001",
- "fleet": "factory-floor",
- "agent_status": "online",
- "agent_version": "1.4.2",
- "last_seen_at": "2026-06-08T09:12:00Z",
- "remote_access": {
- "enabled": true,
- "broker_url": "wss://broker.smarttouch.local:8443",
- "allowed_protocols": [
- "shell",
- "diagnostics"
]
}, - "certificate": {
- "subject": "CN=sensor-001,OU=remote-access,O=smarttouch",
- "serial": "4a:f3:1b:cc:00:de",
- "issued_at": "2026-06-08T00:00:00Z",
- "expires_at": "2027-06-08T00:00:00Z"
}
}
}Update the display name or fleet label of a device. Certificate and agent configuration cannot be changed through this endpoint.
| deviceId required | string Example: sensor-001 Unique device identifier (e.g., |
| display_name | string New human-readable name for the device |
| fleet | string or null Fleet label to assign. Set to null to remove fleet membership. |
{- "display_name": "Temperature Sensor 001 (Revised)",
- "fleet": "assembly-line"
}{- "status": 200,
- "data": {
- "id": "sensor-001",
- "display_name": "Temperature Sensor 001",
- "fleet": "factory-floor",
- "agent_status": "online",
- "agent_version": "1.4.2",
- "last_seen_at": "2019-08-24T14:15:22Z",
- "remote_access": {
- "enabled": true,
- "broker_url": "wss://broker.smarttouch.local:8443",
- "allowed_protocols": [
- "shell"
]
}, - "certificate": {
- "subject": "CN=sensor-001,OU=remote-access,O=smarttouch",
- "serial": "4a:f3:1b:cc:00:de",
- "issued_at": "2019-08-24T14:15:22Z",
- "expires_at": "2019-08-24T14:15:22Z"
}
}
}Permanently removes a device from the platform registry.
Any open sessions to this device are closed immediately.
This action cannot be undone. Requires the administrator role.
| deviceId required | string Example: sensor-001 Unique device identifier (e.g., |
{- "error": "unauthorized",
- "message": "Bearer token is missing or has expired.",
- "status": 401
}Returns the current connection state of the Remote Access Agent on the device. Use this endpoint to verify the agent is online before opening a session.
| deviceId required | string Example: sensor-001 Unique device identifier (e.g., |
{- "status": 200,
- "data": {
- "device_id": "sensor-001",
- "agent_status": "online",
- "connected_at": "2026-06-08T08:55:32Z",
- "broker_url": "wss://broker.smarttouch.local:8443",
- "latency_ms": 12
}
}