Skip to content

Agent API

The Agent API provides 15 intent-oriented tools at:

POST /v1/agent/{tool}

Every request body includes org_id and fleet_id. The API is designed for automations and LLM-backed integrations that need a smaller, typed surface than low-level resource routes.

Compatibility. Agent request objects reject unknown fields. Use GET /openapi.json for the exact schema of each tool.

Read tools

Tool Purpose
query-entities List robots, features, the operation, templates, schedules, scheduled commands, faults, finished mission history, or Field Rules.
get-entity Read detailed robot, feature, operation, template, or Field Rule data.
get-runtime-status Read live fleet, operation, robot, or schedule status.
get-map-context Read fleet geometry and robot positions.
explain-capability Find robots that advertise an action capability.
resolve Resolve names and ids for robots, features, mission templates, and the fleet operation.

Pagination

Single-kind query-entities calls support opaque keyset cursors. Pass the prior response's next_cursor as cursor. A cursor is bound to the entity kind and exact filters, so using it with a different query returns 400. Legacy numeric offset cursors are not accepted. Multi-kind calls are not pageable.

mission_history contains finished runs only. Use get-runtime-status or GET /v1/mission-runs for active work.

Control tools

Tool Purpose
submit-job Define one mission inline and run or schedule it.
deploy-mission Request a fire-now run of an existing template.
schedule-mission Schedule an existing template.
schedule-command Schedule a non-mission command.
cancel-schedule Cancel a mission or command schedule.
control-operation Start, pause, reset, restart, or otherwise control the fleet operation.
control-mission Pause, resume, cancel, or abort one mission run.
set-mission-priorities Update mission priorities as one batch.
control-robot Start, stop, release, reset, set mode, invoke an action, or update settings.

Submit a job

submit-job creates an enabled reusable mission template and registers its schedule in one request. It requires Idempotency-Key.

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "name": "Inspect north pad",
  "feature_id": "feature-uuid",
  "capabilities": ["inspect"],
  "robot_ids": [],
  "schedule": null,
  "deployment_deadline_ms": 900000
}

An empty robot_ids list allows any eligible robot, one id targets one robot, and multiple ids restrict eligibility to that set. schedule: null requests a fire-now schedule.

A normal response is 201 Created:

{
  "missionId": "template-uuid",
  "scheduleId": "schedule-uuid",
  "status": "scheduled",
  "detail": "Job accepted"
}

Deployment is asynchronous

submit-job, deploy-mission, and schedule-mission return status: "scheduled". This means the schedule was accepted. It does not mean a robot was selected, a run was created, or the robot acknowledged the work.

Follow the result with:

  1. POST /v1/agent/get-runtime-status with schedule_id for live phase, summary, candidate robots, and blocking reasons.
  2. GET /v1/mission-schedule?fleet_id=...&id=... for durable schedule status and failure details.
  3. GET /v1/mission-runs?fleet_id=...&schedule_id=... for runs created by that schedule.
  4. GET /v1/events?fleet_id=...&correlation_id=... for the correlated event timeline.

deploy-mission returns 202 Accepted because robot deployment remains asynchronous. submit-job normally returns 201, but can return 202 when its resources were committed and live runtime synchronization is still pending.

Operation control

Each fleet has one operation, so control-operation.operation_id is optional. Omit it to control the fleet's operation, or include it to assert a specific operation id.

Robot delivery outcomes

Robot-hop tools can optionally wait for an acknowledgement using either wait_for_ack: true or positive wait_for_ack_ms. Do not specify both. Waiting is bounded to 30 seconds and reports delivery, not physical task completion.

Delivery states are dispatched, deferred, agent_received, agent_rejected, and timed_out. A timeout can indicate that only the HTTP wait expired while retries continue.

Bulk control-robot supports up to 100 targets for start, stop, and release. It returns 200 when all targets succeed, 207 for mixed outcomes, and 502 when all fail. Force reset, mode, action invocation, and settings update require exactly one robot.