Skip to content

Fleets

A fleet is a named collection of robots managed as one planning, permission, and operational boundary.

Fleet-scoped paths

Most resource endpoints use:

/v1/orgs/{org_id}/fleets/{fleet_id}/...

The server verifies both organization ownership and fleet access. An organization-scoped API key can reach authorized fleets in its organization. A fleet-scoped key can reach only its bound fleet.

List reachable fleets

GET /v1/orgs/{org_id}/fleets

The response includes only fleets the current actor can view:

{
  "items": [
    { "fleetId": "fleet-uuid", "name": "North yard" }
  ]
}

Manifest

GET /v1/orgs/{org_id}/fleets/{fleet_id}/manifest

The manifest resolves robot, feature, mission-template, and operation names and ids. Since a fleet has one operation, operation is one object or null, not an array.

{
  "robots": [{ "robot_id": "robot-uuid", "name": "Rover 1" }],
  "features": [{ "feature_id": "feature-uuid", "name": "North pad" }],
  "mission_templates": [{ "mission_id": "mission-uuid", "name": "Inspect" }],
  "operation": { "operation_id": "operation-uuid", "name": "North yard operation" }
}

Fleet utilization

GET /v1/fleets/{fleet_id}/utilization?window_ms={ms}&bucket_ms={ms}

Returns productive, available, and idle time for the fleet and per robot, plus a bucketed time series. Permission: fleet:read.

Alerts

GET  /v1/alerts?fleet_id={fleet_id}&days={n}
POST /v1/alerts/ack

Alert reads require fleet:read. Acknowledgement requires fleet:write and accepts:

{ "fleetId": "fleet-uuid", "alertIds": [42, 43] }

Omit alertIds to acknowledge all currently unacknowledged alerts in the fleet.

Command audit log

GET /v1/audit-log?fleet_id={fleet_id}&limit={n}&before={seq}

Returns command.* audit entries, newest first. Use nextCursor or the documented cursor field from the response to continue. Permission: fleet:read.

Correlated event timeline

GET /v1/events?fleet_id={fleet_id}

This endpoint returns the full event timeline, not only command audit rows. Optional filters include event_type, correlation_id, robot_id, mission_id, mission_run_id, start_ms, and end_ms. event_type ending in . is a taxonomy prefix, such as mission..

{
  "items": [
    {
      "id": "event-uuid",
      "eventType": "mission.completed",
      "occurredAtMs": 1785859200000,
      "correlationId": "correlation-uuid",
      "causationId": "event-uuid"
    }
  ],
  "nextCursor": null
}

Events are recorded asynchronously. Use them as a correlated narrative, not as a guaranteed-complete execution ledger. Durable state remains available from mission run, schedule, and resource endpoints.