Skip to content

Fleets

A fleet is a named collection of robots that you plan, dispatch, and monitor together.

What it represents

Fleets group robots within an organization so they can be managed as a unit. Members are granted access per fleet, and a fleet can be shared with another organization with a capped role. Missions, operations, and telemetry are all viewed in the context of the fleet that owns the robots.

The fleet-scoped path

Almost every endpoint in this reference is nested under an organization and a fleet:

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

On every such request the server verifies that the fleet belongs to the organization in the path, and that your API key is allowed to reach it:

  • An organization-scoped key may use any fleet_id that belongs to its organization.
  • A fleet-scoped key may use only its own fleet_id.

A fleet that does not belong to the organization, or that the key cannot reach, returns 403. See Authentication for the permission model.

Authentication

All fleet endpoints are called with an API key. See Authentication.

List fleets

GET /v1/orgs/{org_id}/fleets

Lists the fleets your key can reach in the organization, so you can discover fleet ids instead of configuring them out of band. A fleet-scoped key sees only its one fleet. No special permission beyond a valid key is required, and this endpoint is not rate limited.

Response:

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

Capability discovery

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

Lists every service capability available in the fleet and which robots provide it. Use it to answer questions like "which robots can haul?" before planning work.

Permission: robots:read.

Response:

{
  "items": [
    { "capability": "haul", "robot_refs": ["a1b2…", "c3d4…"] },
    { "capability": "mowing", "robot_refs": ["e5f6…"] }
  ]
}

Each robot_refs entry is a robot id. Fetch a robot's detail with the robot endpoints. Combine capabilities with the robot list filters (for example ?capability=haul&available=true) to find robots that can do a job right now.

Fleet utilization

GET /v1/fleets/{fleet_id}/utilization

Returns a fleet utilization score (productive robot-time divided by available robot-time, from 0 to 1) over a trailing window, plus a bucketed time series. Permission: fleet:read.

Optional query params: window_ms (the trailing window length) and bucket_ms (the size of each time-series bucket). Both default to a one-hour window with hourly buckets and are clamped to a sane range.

Response:

{
  "fleetId": "fleet-uuid",
  "windowMs": 3600000,
  "bucketMs": 3600000,
  "nowMs": 1750262400000,
  "utilization": {
    "score": 0.72,
    "productiveMs": 2592000,
    "availableMs": 3600000,
    "idleMs": 1008000,
    "perRobot": [
      { "robotId": "a1b2…", "productiveMs": 2592000, "availableMs": 3600000, "idleMs": 1008000, "score": 0.72 }
    ]
  },
  "overTime": [
    { "startMs": 1750258800000, "endMs": 1750262400000, "productiveMs": 2592000, "availableMs": 3600000, "idleMs": 1008000, "score": 0.72 }
  ]
}

utilization is the score across the whole window (with a per-robot breakdown); overTime is the same score per bucket for charting.

Fleet alerts

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

Lists recent system alerts for a fleet, newest first. days is optional (default 7, maximum 30). Permission: fleet:read.

Response:

{ "alerts": [ { "id": 42, "kind": "…", "severity": "warn", "summary": "…", "occurredAt": "…" } ] }

POST /v1/alerts/ack

Marks alerts acknowledged (seen). Permission: fleet:write.

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

Omit alertIds to acknowledge every unacknowledged alert in the fleet (up to 1000 ids per call when listed). Response:

{ "updated": 2, "acknowledgedBy": "actor-id" }

Command audit log

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

Returns the fleet's command audit log, newest first: who issued which command, against which robots, and whether it was authorized. Permission: fleet:read. limit is optional (default 50, maximum 200); pass before (an entry id) to page backwards.

Response:

{
  "entries": [
    {
      "id": 9001,
      "occurredAt": "2026-06-18T16:00:00Z",
      "userId": "user-or-key-id",
      "userName": "Jordan",
      "fleetId": "fleet-uuid",
      "fleetName": "North yard",
      "robots": [ { "id": "a1b2…", "name": "Rover-1" } ],
      "operationId": null,
      "missionId": null,
      "commandType": "missionCommand",
      "commandName": "Morning sweep",
      "status": "authorized",
      "source": "rest_api"
    }
  ]
}

This is the broad command trail across the fleet. For the narrower trail of plan and operation events from automation, see the activity log.

Managing fleets

Creating, renaming, sharing, and deleting fleets is done in the Fleet Manager web app. These administrative actions are not exposed to API keys in this version of the API.