Features

A feature is a named piece of map geometry in a fleet: a shape (such as a point, line, or polygon) or a route. Features describe places and paths that plans reference, for example a load location, a dump zone, or a queue.

What it represents

Features are the spatial building blocks an operation refers to by id. When you create a plan, its payload points at features by their ids. The endpoints here let you list the features available in a fleet and read one in detail, so you can discover the ids and geometry to reference.

Authentication

Feature endpoints are called with an API key. Reads require the features:read permission; creating, editing, deleting, and the resource-control actions (reset decomposer, lock) require features:write. See Authentication.

List features

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

Returns a summary for each feature in the fleet, newest first. Optional query filters:

Filter	Description
feature_type	Match the geometry variant (for example Point, Polygon, LineString).
state	Match the feature's role classification.

Response:

{
  "items": [
    {
      "feature_id": "f1a2…",
      "name": "Stockpile",
      "feature_type": "Polygon",
      "spatial_data_type": "shape",
      "feature_role": "zone",
      "updated_at": "2026-06-18T16:00:00Z"
    }
  ],
  "next_cursor": null
}

spatial_data_type is shape or route. feature_role is the role classification used when the feature was defined.

Get one feature

GET /v1/orgs/{org_id}/fleets/{fleet_id}/features/{feature_id}

Returns the full feature, including its geometry. A feature that does not belong to the fleet in the path returns 404.

Response:

{
  "feature_id": "f1a2…",
  "name": "Stockpile",
  "feature_type": "Polygon",
  "spatial_data_type": "shape",
  "feature_role": "zone",
  "scope": "fleet",
  "spatial_data": { "polygon": { "exterior": [ { "lat": 45.5, "lon": -122.6 } ] } },
  "min_z_m": 0.0,
  "max_z_m": 0.0,
  "level_id": 0,
  "updated_at": "2026-06-18T16:00:00Z"
}

spatial_data holds the geometry; its shape depends on feature_type. min_z_m, max_z_m, and level_id describe the vertical extent and map level.

Create or update a feature

POST /v1/features

Creates a feature when the body has no id, or updates the named feature when an id is present. Permission: features:write. Updating a feature that belongs to a different fleet is rejected with 403.

Body (the geometry fields depend on whether the feature is a shape or a route):

{
  "id": "feature-uuid",
  "fleetId": "fleet-uuid",
  "name": "Stockpile",
  "areaType": "zone",
  "isRoute": false,
  "scope": "fleet",
  "shapeType": "polygon",
  "shapeData": { "polygon": { "exterior": [ { "lat": 45.5, "lon": -122.6 } ] } },
  "minZM": 0,
  "maxZM": 0,
  "levelId": 0
}

• fleetId, name, and areaType are required.
• isRoute selects a route (true) or a shape (false, the default).
• For a shape, provide shapeType and shapeData; for a route, provide routeType and routeData.
• Omit id to create; include it to update an existing feature.

Response:

{ "success": true, "id": "feature-uuid", "draftRev": 2, "isRoute": false, "message": "Feature \"Stockpile\" draft saved (rev 2)" }

Delete a feature

DELETE /v1/features/{id}?isRoute=false

Deletes a feature. Permission: features:write. Deleting a feature that does not exist is a no-op and still returns success.

Response:

{ "success": true }

Reset a feature's decomposer

POST /v1/orgs/{org_id}/fleets/{fleet_id}/features/{feature_id}/reset-decomposer

Clears the feature's resource holders and advances its decomposition so it can be re-divided among robots. Permission: features:write. The feature must belong to the fleet in the path.

Response:

{ "success": true, "featureId": "feature-uuid" }

Lock or unlock a feature

PUT /v1/orgs/{org_id}/fleets/{fleet_id}/features/{feature_id}/lock

Sets or clears a feature's resource lock. Permission: features:write. The feature must belong to the fleet in the path.

Body:

{ "locked": true, "lockReason": "Reserved for the morning shift" }

lockReason is optional. Response:

{ "success": true, "featureId": "feature-uuid", "locked": true }

Configure how a feature is divided

PUT /v1/orgs/{org_id}/fleets/{fleet_id}/features/{feature_id}/decomposition

Sets how a feature's area is divided among robots: the selection policy, coverage method, spacing, lease limit, completion area, and whether the feature requests robots while it has open capacity. Applying it releases all current holds and re-divides the feature. Permission: features:write. The feature must already exist (create it first with POST /v1/features), and the featureId in the body must match the path.

{
  "featureId": "feature-uuid",
  "geometryPolicy": "sharedStatic",
  "coverageMethod": "hexagonal",
  "spacing": 1.0,
  "leaseGrantLimit": 3,
  "completionAreaType": "coverage",
  "createsDemand": true
}

Every field except featureId is optional and falls back to a sensible default.

createsDemand (default false) controls whether the feature actively pulls in robots. By default, only consumable work areas (or steps with a run limit) request robots, so a shared or exclusive feature stays idle until a job explicitly sends a robot to it. Set createsDemand to true to have the feature request robots whenever it still has open capacity. This is useful for exclusive spots such as charging bays, parking spots, or staging queues that should draw in an available robot as soon as a slot frees up.

Response:

{ "success": true, "featureId": "feature-uuid" }

Drawing features

Drawing feature geometry visually is done in PathLab in the Fleet Manager web app. The endpoints above let automation create, edit, and control features programmatically.

Related

• Fleets
• Operations