Robot SDK: ROS 2 + REST.

Authentication

Every request must include an Authorization: Bearer header. Tokens are scoped to a fleet and rotate from Anchor, so a leaked token can only ever touch one fleet and stops working at the next rotation.

curl https://api.klerix.com/v1/fleets \
  -H "Authorization: Bearer $KLERIX_TOKEN"

Base URL & versioning

All endpoints live under https://api.klerix.com/v1. The version is pinned in the path, so v1 will not change shape under you. New fields may be added to responses over time, so parse defensively and ignore keys you do not use.

Missions

A mission is one execution of a skill on a robot. Start one with a POST, then either poll the mission or subscribe to an event hook.

POST /v1/robots/{id}/skills:run

{
  "input": { "skill": "palletize-euro" },
  "mission_id": "msn_line7_84221"
}

The call returns a mission_id. Poll GET /v1/missions/{mission_id} for status, which moves through queued, running, then succeeded or failed. Supplying your own mission_id makes the request idempotent: retrying with the same ID will not start a second run.

Skills

List the skills available to a fleet, or fetch one to read its inputs and safety class.

GET /v1/fleets/{id}/skills
GET /v1/skills/{skill_id}

Skills are versioned. Pin a specific version in a mission with "skill": "palletize-euro@4", or omit the version to use the current stable bundle.

Fleet telemetry

Read cycle time, throughput, OEE, energy, and safety counters for a fleet. Results are cursor-paginated and newest first.

GET /v1/fleets/{id}/telemetry?limit=25&cursor="..."

Teleop

When a robot needs a human, it opens a teleop request rather than stopping the line. Subscribe to teleop.requested, then claim the session to drive or correct the robot. Every teleop action is recorded in the same action trace as autonomous steps.

POST /v1/teleop/{session_id}:claim
POST /v1/teleop/{session_id}:release

Event hooks

Subscribe to fleet events instead of polling. Each delivery is signed with X-Klerix-Signature, so verify the signature before trusting the payload.

Common events: mission.started, skill.step, teleop.requested, safety.event, ota.completed.

{
  "event": "mission.succeeded",
  "mission_id": "msn_84221",
  "skill": "palletize-euro",
  "output": { "completed": true }
}

ROS 2 bridge

The bridge exposes the same objects as ROS 2 topics and services, so you can drive Klerix from an existing robotics stack. Topics cover fleets, robots, skills, missions, telemetry, teleop sessions, safety events, and OTA updates.

# start a mission via the ROS 2 service
ros2 service call /klerix/run_skill klerix_msgs/srv/RunSkill \
  "{robot: 'rbt_cell07_arm02', skill: 'palletize-euro'}"

# subscribe to safety events
ros2 topic echo /klerix/safety_events

Pagination

List endpoints return a next_cursor when more results exist. Pass it back as cursor to fetch the next page. When next_cursor is null, you have reached the end.

{ "data": [ ... ], "next_cursor": "eyJvIjoyNX0" }

Rate limits

The API allows 600 requests per minute per token. Each response includes X-RateLimit-Remaining and X-RateLimit-Reset. A request over the limit returns 429; back off and retry after the reset window. Telemetry and event hooks do not count against this budget.

Errors

The API uses standard HTTP status codes. Error bodies share one shape:

{ "error": { "code": "skill_not_found", "message": "No skill 'palletize-euro' in fleet flt_7" } }

Retry idempotent requests on 409 and 5xx with exponential backoff. For mutating calls, reuse the same mission_id so a retry never double-runs a robot.