Platform / Fleet

Fleet cohorts and tags

Cohorts are the targeting unit for the fleet. A cohort is a named group or site that both robots and service agents join, statically or by rule, and tags are a free-form label array on the same two entity types. Every fleet surface filters on them, and the active filter is carried in the URL.

API docs

01 Cohort kinds

details

group

An arbitrary grouping: a customer, a shift, a hardware revision. Carries a name and an optional description.

site

A physical location. Accepts optional site_meta with building, floor, and zone (each up to 120 characters), rendered wherever the site appears.

02 Membership

details

Static membership

A membership row links a cohort to one robot_id or one service_agent_id. Robots and service agents can sit in the same cohort. A robot in pending state (pre-registered, not yet claimed) is a full member: cohorts never require a linked service agent.

Rule-based membership

A cohort's rules map matches robots at read time, with no membership rows written. Rule-based members are distinguished from static members in the console.

Deleting a cohort

Membership rows are deleted, member robots and agents are untouched, and any enrollment token bound to the cohort has its binding cleared.

Decommissioned robots and membership

Retiring a robot does not remove it from a cohort. Its static membership row survives and is still returned by GET /api/v1/operator/cohorts/:id, so the record of where a unit lived is not rewritten by retiring it. What excludes decommissioned robots is the working roster: the robot-in-cohort query behind the console's member board, the rule-match count, and rule-based membership all filter them out, so "this rule matches N robots" stays a count of units that can actually be dispatched or updated.

03 Rule keys

reference

Key	Match	Notes
robot_type	Exact string	One of amr, drone, manipulator, humanoid
manufacturer	Exact string	Robot manufacturer
model	Exact string	Robot model
firmware_version	Exact string	Robot firmware version
capabilities	Array overlap	Matches a robot with any listed capability
tags_any	Array overlap	Matches a robot carrying any listed tag

04 Limits

details

Name

2-120 chars

Unique per workspace. A duplicate name is a validation error.

Rule values

32 per key

Each rule key accepts at most 32 values.

Listing

100 / 500

Cohort and membership listings default to 100 rows and accept limit up to 500.

05 Operator API

reference

Method and path	Purpose	Success
GET /api/v1/operator/cohorts	List cohorts with member_count	200
POST /api/v1/operator/cohorts	Create a cohort	201
GET /api/v1/operator/cohorts/:id	Show a cohort with its members	200
PATCH /api/v1/operator/cohorts/:id	Update name, description, meta, rules	200
DELETE /api/v1/operator/cohorts/:id	Delete a cohort	204
POST /api/v1/operator/cohorts/:cohort_id/members	Add one member	201
DELETE /api/v1/operator/cohorts/:cohort_id/members/:membership_id	Remove a membership by membership id, not robot id	204

06 Create a site cohort with a rule

example

json

POST /api/v1/operator/cohorts

{
  "cohort": {
    "name": "Rotterdam DC",
    "kind": "site",
    "description": "Night shift AMRs",
    "site_meta": {"building": "DC-2", "floor": "1", "zone": "east"},
    "rules": {
      "robot_type": ["amr"],
      "tags_any": ["night-shift"]
    }
  }
}

07 Filtering fleet surfaces

details

Shared query parameters

cohort_id (a cohort UUID) and tag (a single tag string) filter the fleet board, missions, fleet alerts, diagnostics, and fleet analytics. Both are reflected in the console URL, so a filtered view is shareable as a link. On the operator API the same two parameters are accepted flat (?cohort_id=...) or nested (?filter[cohort_id]=...).

Selection round-trip

Bulk operations accept the same filter keys the fleet board puts in the URL -- query, status, robot_type, cohort_id, tag -- which is what lets "select all matching" carry a filtered view into a batch.

Related docs