Fleet
Fleet cohorts and tags
Organize robots and service agents into named groups or sites, add lightweight tags, and reuse those selections across fleet work. Membership can be explicit or rule-based, and active filters stay in the URL for sharing.
On this page
Start here
Cohorts and tags turn a workspace into understandable operating slices. Use a site for physical location, a group for another durable grouping, rules for automatic matching, and tags for filterable labels.
Before you begin
- An active owner, admin, or member role for cohort changes; auditors have read-only access
- A naming convention and attributes that support the intended selection
Put it into practice
-
Define the grouping
Choose group or site, give it a unique name, and add site metadata only when building, floor, or zone helps operators.
-
Add members deliberately
Use static membership for an explicit roster or supported rules for membership evaluated at read time. Pending robots may be members before they are claimed.
-
Reuse the selection
Filter the fleet board and related surfaces by cohort_id or tag. Keep the resulting URL when sharing an operational view or creating work from that selection.
The cohort shows the expected robots or service agents, a shared filtered URL reproduces that selection, and removing the cohort leaves the underlying members intact.
01 Cohort kinds
detailsgroup
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
detailsStatic membership
A static membership 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 is still returned by GET /api/v1/operator/cohorts/:id and preserves where the unit lived. The working roster excludes it: the console member board, rule-match count, and rule-based membership filter out decommissioned robots, so "this rule matches N robots" counts units that can still 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
detailsName
2-120 chars
Unique per workspace. A duplicate name is a validation error.
Rule values
32 per array key
robot_type, manufacturer, model, and firmware_version each accept a single string. Only capabilities and tags_any are arrays, each capped at 32 values. Sending robot_type as an array fails Cohort.changeset validation.
Tags
32 × 64
Robots and service agents accept at most 32 tags of 64 characters each. Tags are lowercased, trimmed, and deduped. The same limits apply to default_tags on claim tokens and to apply_tags / remove_tags batches.
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 plus a bounded page of static membership rows (default 100, max 500). Rule-matched robots are not membership rows; load them with GET /api/v1/operator/robots?cohort_id= | 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
examplePOST /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
detailsShared 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.
Troubleshooting
- A rule-based member has no membership record
- That is expected. Rules are evaluated when members are read; they do not write static membership rows.
- A filter returns an empty fleet
- Check cohort kind, supported rule keys, tag spelling, and whether the entity is decommissioned. Clear one URL filter at a time to locate the mismatch.
- A deleted cohort was bound to enrollment
- Deleting the cohort clears enrollment-token binding but does not delete robots or agents. Update the enrollment setup before the next claim.