Local HTTP API

Address and request formatCopy Anchor Link

The local HTTP API shares devices and settings with the console. Run roboapi http, then use http://127.0.0.1:8080. For direct cloud inference, use the cloud API.

POST requests use Content-Type: application/json and a JSON object body; send {} when no parameters are needed. The body limit is 16 KiB, or 128 KiB for presets and storage cleanup. Local endpoints have no account authentication. Use SSH forwarding for remote access; browser writes must be same-origin.

Status and videoCopy Anchor Link

curl --fail-with-body http://127.0.0.1:8080/api/status

mode is idle, running or paused. Check control_ready and device/model connections before starting; arm_connected describes the arm connection alone. Reconnect to the stream URL if the video stream ends.

Tasks and run controlCopy Anchor Link

Instructions must contain 1–1000 characters after trimming. HTTP starts use run_source: "web"; updates, pause and resume require a matching owner. Stop an Agent-owned run before starting over HTTP.

Optional new_task defaults to false. The same instruction as the current local task continues that task, appending elapsed time and video; a different instruction creates a task. True always creates a new local task, even for the same instruction. Each start begins a run; a local task ID is not a cloud session ID.

An accepted start does not mean the first background inference succeeded. Runs continue until stopped or faulted. /api/instruction does not interrupt the current action chunk. To reproduce the browser's new-task behavior during a run, call stop, confirm mode: "idle", then start with new_task: true.

Model settings and presetsCopy Anchor Link

List available modelsCopy Anchor Link

Call POST /api/policy/models to query the model service through the local runtime:

{"url": "https://api.pokebot.com/v1"}

url is required and api_key is optional. Omit the key to use saved local credentials, or include api_key to try a new key. Do not send an empty string. Success returns the actual model IDs available to that key:

{"models": ["MODEL_ID"]}

This request only retrieves the list. It does not save the address or credentials, or create a task session. Retrieve the list again after changing the address or key. An empty list or failed connection returns 502 and keeps saved settings unchanged. MODEL_ID is illustrative; use an ID from the actual response when saving configuration.

Save connection and runtime settingsCopy Anchor Link

Call POST /api/policy/config while idle. url, model and inter_chunk_pause_s are required; api_key is optional. Omit the key to retain existing credentials; do not send an empty string. Settings are saved after a /models check; failure preserves the previous values.

{
  "url": "https://api.pokebot.com/v1",
  "model": "MODEL_ID",
  "inter_chunk_pause_s": 0.5
}

Use the official Base URL, https://api.pokebot.com/v1, and replace MODEL_ID with an ID returned by its /models endpoint. inter_chunk_pause_s is a non-negative wait in seconds after a chunk and before the next observation. The service must meet the local runtime protocol.

Save presetsCopy Anchor Link

POST /api/presets saves presets without running a task:

{"instructions": ["Pick up the block", "Place it in the tray"]}

Up to 20 instructions are allowed, each with 1–1000 characters.

Calibration actionsCopy Anchor Link

All paths are POST /api/calibration/{action}. Complete the on-site preparation in coordinate calibration first.

HTTP confirm_plane_c does not replace the separate save and enable_control calls. Confirmation fields must reflect the on-site operator's actual confirmation. Closing the browser does not cancel teaching; use /api/devices/release to discard it.

Direction checkCopy Anchor Link

POST /api/calibration/check takes exactly one field:

{"direction":"forward"}

direction accepts forward, left, up or home. The first three move 5 cm and rotate 30° from Home, then return. home only returns. All preserve gripper opening. See direction check for the axes. The request returns after motion finishes. /api/stop interrupts it and cancels the remaining return path.

Motion rangeCopy Anchor Link

POST /api/workspace/config accepts a complete configuration. Positions are absolute model-frame coordinates in metres, unlike the UI's distances from Home in centimetres.

{
  "enabled": true,
  "min_xyz_m": [-0.73, -1.06, -0.11],
  "max_xyz_m": [0.47, 0.14, 1.09]
}

These defaults are Home ±0.60 m. Each array must contain three finite numbers, each minimum must be below its maximum, and the range must contain Home [-0.13,-0.46,0.49]. Save while idle after finishing teaching. Saving does not move the robot.

When enabled, out-of-range flange-centre targets are clipped to the boundary and the task continues. Rotation is unaffected. Starting, resuming or moving manually requires the measured pose inside the range; an explicit Home return can start outside. The boundary does not constrain the entire arm, external forces, compliance or tracking error, and does not provide obstacle avoidance.

Tasks, recordings and storageCopy Anchor Link

recording is off, recording, saving, ready or error. Wait for a saving video to finish before downloading or cleaning it up.

Cleanup kind is recordings (videos only, retaining instructions and feedback) or tasks (complete records). Omitting task_ids selects all tasks; an empty array selects none. Batch cleanup skips running tasks and tasks saving video. Individual deletion of these tasks returns 409.

Failure responsesCopy Anchor Link

Failures usually return {"error":"readable reason"}. An unmet control prerequisite may include "kind":"control_not_ready".

After a network timeout, read /api/status before repeating start, Home or calibration actions. See local runtime errors.