BetterDesk/docs/cdap/API_REFERENCE.md

CDAP REST API Reference

All CDAP management endpoints require API key authentication via X-API-Key header.

Base URL: http://your-server:21114/api

Endpoints

Gateway Status

GET /api/cdap/status

Returns CDAP gateway status and connected device count.

Response:

{
    "enabled": true,
    "connected_devices": 5,
    "uptime_seconds": 86400,
    "version": "0.3.0"
}

List Connected Devices

GET /api/cdap/devices

Returns all currently connected CDAP devices.

Response:

{
    "devices": [
        {
            "id": "CDAP-6A9A5452",
            "name": "Office Workstation",
            "type": "os_agent",
            "version": "1.0.0",
            "platform": "linux/amd64",
            "connected_at": "2026-03-21T10:30:00Z",
            "capabilities": ["telemetry", "commands", "terminal"],
            "widget_count": 9
        }
    ]
}

Device Info

GET /api/cdap/devices/{id}/info

Returns detailed info for a specific connected device.

Response:

{
    "id": "CDAP-6A9A5452",
    "name": "Office Workstation",
    "type": "os_agent",
    "version": "1.0.0",
    "platform": "linux/amd64",
    "connected_at": "2026-03-21T10:30:00Z",
    "capabilities": ["telemetry", "commands", "terminal", "file_transfer"],
    "uptime": "3d 12h 45m"
}

Device Manifest

GET /api/cdap/devices/{id}/manifest

Returns the full device manifest including widget definitions.

Device Widget State

GET /api/cdap/devices/{id}/state

Returns current widget values for the device.

Response:

{
    "values": {
        "sys_cpu": 23.5,
        "sys_memory": 67.2,
        "sys_disk": 45.0,
        "sys_hostname": "office-pc",
        "sys_uptime": "3d 12h"
    },
    "updated_at": "2026-03-21T10:35:00Z"
}

Send Command

POST /api/cdap/devices/{id}/command

Send a command to a connected device. Requires operator role.

Request:

{
    "command": "system_reboot",
    "args": {}
}

Response:

{
    "command_id": 42,
    "status": "sent"
}

Audio Session (WebSocket)

GET /api/cdap/devices/{id}/audio
Upgrade: websocket

WebSocket endpoint for bidirectional audio streaming. Requires operator role.

Protocol:

1. Client sends { type: "init" } to start audio session
2. Server responds { type: "ready", codec: "pcm", sample_rate: 48000, channels: 1 }
3. Client sends/receives { type: "audio_frame", data: "<base64>", timestamp: 123 }
4. Client sends { type: "close" } to end session

Error Responses

All errors follow a consistent format:

{
    "error": "device_not_found",
    "message": "Device CDAP-XXXX is not connected"
}

HTTP Status	Error Code	Description
401	unauthorized	Missing or invalid API key
403	forbidden	Insufficient role for operation
404	device_not_found	Device not connected
503	cdap_disabled	CDAP gateway not enabled