Skip to main content

​
Robotics

The Robotics API lets you run programmable robot behaviors using simple HTTP calls. Pi orchestrates perception, behavior evaluation, and decision/action dispatch — returning async job envelopes you can poll or react to via SSE.
Keep SSE connections alive and implement automatic reconnection. Pi emits real-time incident, state, action, and log events over the event stream. Reconnect using the same query parameters if the connection drops.

​
Start a robot run

POST /api/v1/robots/run Queues a perception + behavior + decision job for a robot. Returns 202 Accepted with a job_id.

​
Request

curl -sS -X POST "$PI_BASE_URL/api/v1/robots/run" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "robot_id": "robot_123",
    "task": "patrol",
    "profile": "patrol_security",
    "zones": [
      {
        "name": "entrance",
        "type": "patrol",
        "frame": "map",
        "polygon": [[0,0],[10,0],[10,10],[0,10]]
      }
    ],
    "behaviors": [
      { "type": "intrusion", "zone": "entrance" }
    ],
    "actions": [
      {
        "on": "intrusion",
        "do": [
          { "type": "alert", "severity": "critical" },
          { "type": "command", "command": { "command": "announce", "message": "Restricted area." } }
        ]
      }
    ],
    "perception": {
      "input": { "data": "<base64_or_data_url>", "mime_type": "image/png" },
      "frame_index": 0,
      "detect": ["person"]
    },
    "outputs": { "delivery": ["sse"] }
  }'

​
Body parameters

​
robot_id
string
required
Unique identifier for the robot. Max 128 characters.
​
task
string
Robot task type. One of "patrol", "observe", "follow", "approach", "inspect", "custom". Defaults to "patrol".
​
profile
string
Robot behavior preset. One of "patrol_security", "warehouse_inspector", "delivery_monitor", "agriculture_scout", "cleaning_robot", "custom".
​
zones
array
Zone definitions for the run. Each zone includes name, type ("patrol", "restricted", "waypoint", "boundary", "custom"), frame (coordinate frame, e.g. "map"), and polygon (array of [x, y] pairs, min 3). Max 200 zones.
​
behaviors
array
Behavior rules for this run. Supports all surveillance behavior types (loitering, intrusion, crowd_growth, object_left, perimeter_breach, speed_violation, wrong_direction) plus robot-specific types: patrol, follow_target, approach_on_incident, record_on_incident. Max 100 rules.
​
actions
array
Action rules triggered on behavior events. Each rule includes on (behavior type) and do (array of actions). Action types: "alert", "command", "webhook", "noop". Max 200 rules.
​
perception
object
Perception configuration for this run.
​
outputs
object
Delivery configuration.

​
Response (202)

{
  "id": "req_pi_...",
  "object": "job",
  "status": "queued",
  "created_at": 1711900000,
  "data": { "job_id": "<uuid>" }
}
Poll GET /api/v1/jobs/:id for the completed run output, which includes robot_id, task, robot state, incidents, and actions_executed.

​
Get robot status

GET /api/v1/robots/:id/status Returns the robot record and current state from the ROS2 bridge sidecar when available.

​
Path parameters

​
id
string
required
The robot identifier (same as robot_id used in the run request).

​
Response fields

​
robot_id
string
The robot identifier.
​
status
string
One of "offline", "idle", "busy", "error".
​
battery_pct
number | null
Battery percentage (0–100) when reported by the ROS2 bridge.
​
position
object
Current position including frame, x, y, optional z, and heading_deg.
​
last_seen_at
integer
Unix timestamp of the last state report.

​
Send a direct command

POST /api/v1/robots/:id/command Dispatch a command directly to the robot via the ROS2 bridge sidecar. Useful for manual overrides and emergency stops.

​
Path parameters

​
id
string
required
The robot identifier.

​
Request

curl -sS -X POST "$PI_BASE_URL/api/v1/robots/robot_123/command" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": {
      "command": "move_to",
      "target": { "frame": "map", "x": 1.2, "y": 3.4 }
    }
  }'

​
Body parameters

​
command
object
required
The command to dispatch.

​
Subscribe to robot events (SSE)

GET /api/v1/robots/events Opens a persistent text/event-stream connection. Pi emits typed robot events in real time.

​
Consuming SSE events

curl -N "$PI_BASE_URL/api/v1/robots/events" \
  -H "Authorization: Bearer $PI_API_KEY" \
  -H "Accept: text/event-stream"

​
SSE event shape

​
id
string
UUID of the event.
​
object
string
Always "robot.event".
​
robot_id
string
The robot that emitted the event.
​
type
string
Event type: "state" (position/battery update), "incident" (behavior trigger), "action" (executed action log), or "log" (free-form message).
​
created_at
integer
Unix timestamp.
​
state
object
Present for type: "state" events. Includes status, battery_pct, position, and last_seen_at.
​
incident
object
Present for type: "incident" events. Full incident object matching the surveillance incident schema.
​
action
object
Present for type: "action" events. Includes rule_on, executed (actions dispatched), and errors.
​
message
string
Present for type: "log" events.