📡 API Documentation

🔧 PicoClaw Edge API

Each PicoClaw edge node exposes a local HTTP API for receiving commands from the cloud and reporting status.

POST /api/command

Send a command to the edge node for execution.

POST http://<edge-ip>:18791/api/command
Authorization: Bearer edge-secret-token
Content-Type: application/json

{
  "command_id": "cmd-20260214-001",
  "type": "exec",
  "priority": "high",
  "payload": {
    "action": "enable_backup_cooling",
    "params": {"target": "rack-01-ac-backup"}
  },
  "timeout_seconds": 30,
  "callback_url": "https://openclaw.example.com/fleet/callback"
}

// Response 200
{
  "command_id": "cmd-20260214-001",
  "status": "executed",
  "result": {"message": "Backup cooling enabled successfully"},
  "duration_ms": 1250
}

GET /api/status

Get current node status including system metrics and sensor readings.

GET http://<edge-ip>:18791/api/status
Authorization: Bearer edge-secret-token

// Response 200
{
  "node_id": "datacenter-rack-01",
  "node_group": "datacenter-monitoring",
  "uptime_hours": 720,
  "system": {
    "cpu_percent": 12.5,
    "mem_used_mb": 6.2,
    "mem_total_mb": 256,
    "disk_used_percent": 15
  },
  "capabilities": ["temperature", "humidity", "ups_status", "shell_exec"],
  "channels": {
    "telegram": "connected",
    "feishu": "connected",
    "maixcam": "disconnected"
  },
  "last_sensor_reading": {
    "timestamp": "2026-02-14T15:30:00Z",
    "temperature": 24.5,
    "humidity": 55
  }
}

GET /api/health

Simple health check endpoint for heartbeat monitoring.

GET http://<edge-ip>:18791/api/health

// Response 200
{"status": "ok", "version": "0.3.2", "node_id": "datacenter-rack-01"}

POST /api/message

Forward a user message to the edge agent's processing loop.

POST http://<edge-ip>:18791/api/message
Authorization: Bearer edge-secret-token
Content-Type: application/json

{
  "channel": "api",
  "from": "cloud-operator",
  "text": "What's the current temperature in rack 01?",
  "session_id": "cloud-session-001"
}

// Response 200
{
  "response": "Rack 01 temperature is 24.5°C (normal range). Humidity is 55%.",
  "session_id": "cloud-session-001"
}

☁️ OpenClaw Fleet API

The Fleet Manager on OpenClaw provides endpoints for device registration, event collection, and command dispatch.

POST /fleet/register

Edge node registers itself with the cloud on startup.

POST https://openclaw.example.com/fleet/register
Content-Type: application/json

{
  "node_id": "datacenter-rack-01",
  "node_group": "datacenter-monitoring",
  "api_url": "http://192.168.1.50:18791",
  "capabilities": ["temperature", "humidity", "ups_status"],
  "version": "0.3.2",
  "hardware": "LicheeRV-Nano-WiFi6"
}

// Response 201
{
  "status": "registered",
  "heartbeat_interval_seconds": 10,
  "report_interval_seconds": 30
}

POST /fleet/heartbeat

Periodic heartbeat from edge node (every 10 seconds by default).

POST https://openclaw.example.com/fleet/heartbeat
{
  "node_id": "datacenter-rack-01",
  "timestamp": "2026-02-14T15:30:10Z",
  "cpu_percent": 12.5,
  "mem_used_mb": 6.2,
  "uptime_hours": 720,
  "agent_sessions": 3
}

POST /fleet/events

Report events (alerts, status changes, resolved incidents) to the cloud.

POST https://openclaw.example.com/fleet/events
{
  "node_id": "datacenter-rack-01",
  "node_group": "datacenter-monitoring",
  "type": "alert",
  "severity": "critical",
  "timestamp": "2026-02-14T15:30:00Z",
  "payload": {
    "sensor": "temperature",
    "value": 42.5,
    "threshold": 40.0,
    "message": "Rack temperature exceeded threshold: 42.5°C > 40°C",
    "action_taken": "Backup AC enabled automatically"
  }
}

📡 Communication Protocols

Protocol	Use Case	Direction
REST (HTTP/HTTPS)	Commands, status queries, event reports	Cloud ↔ Edge
WebSocket	Real-time streaming, live dashboard	Cloud → Edge
MQTT	Lightweight publish/subscribe for IoT	Edge → Cloud
TCP (JSON)	MaixCAM sensor device communication	Device → PicoClaw

🔐 Authentication