docs/api reference/robots

Robots API

Endpoints

GET

/robots

List all robots in your workspace.

POST

/robots

GET

/robots/{id}

Get a single robot by ID.

PUT

/robots/{id}

Update robot name, type, or metadata.

DELETE

/robots/{id}

Remove a robot from the fleet.

GET

/robots/{id}/status

Get real-time status and resource metrics.

GET

/robots/{id}/logs

Retrieve agent logs for a time window.

List Robots

GET/robots

bash

curl https://api.kairo.dev/v1/robots \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx"

json

// 200 OK
{
  "data": [
    {
      "id": "rob_a1b2c3d4",
      "name": "my-arm-01",
      "type": "manipulator",
      "status": "online",
      "ros_distro": "humble",
      "fleet_id": "flt_xyz123",
      "active_model": "mdl_abc123",
      "created_at": "2026-01-15T10:30:00Z",
      "last_seen": "2026-03-23T11:59:42Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Register a Robot

POST/robots

Field	Type	Required	Description
name	string	Yes	Human-readable name for the robot.
type	string	Yes	Robot type: manipulator, mobile, aerial, humanoid, or custom.
ros_distro	string	No	ROS 2 distribution (e.g. humble). Auto-detected if omitted.
fleet_id	string	No	Fleet to assign the robot to on registration.
metadata	object	No	Arbitrary key-value metadata (e.g. location, serial number).

bash

curl -X POST https://api.kairo.dev/v1/robots \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "warehouse-arm-01",
    "type": "manipulator",
    "ros_distro": "humble",
    "metadata": { "location": "bay-3", "serial": "ARM-2024-001" }
  }'

json

// 201 Created
{
  "id": "rob_newid123",
  "name": "warehouse-arm-01",
  "type": "manipulator",
  "status": "offline",
  "created_at": "2026-03-23T12:00:00Z"
}

Get Robot Status

GET/robots/{id}/status

bash

curl https://api.kairo.dev/v1/robots/rob_a1b2c3d4/status \
  -H "Authorization: Bearer kai_live_xxxxxxxxxxxx"

json

// 200 OK
{
  "id": "rob_a1b2c3d4",
  "status": "online",
  "active_model": "mdl_abc123",
  "model_version": "v2",
  "uptime_s": 86400,
  "metrics": {
    "inference_latency_p50_ms": 11,
    "inference_latency_p99_ms": 24,
    "error_rate": 0.002,
    "throughput_rps": 18.4,
    "cpu_percent": 34,
    "memory_percent": 41
  },
  "last_heartbeat": "2026-03-23T11:59:42Z"
}

ℹ

Status metrics are updated with each heartbeat (every 30 s by default). For higher-frequency monitoring, use the kairo monitor CLI command which streams data over WebSocket.

←

API Reference

Models API

→

Was this page helpful?