Collections
Collections let you group entities — devices, sites, or customers — using flexible, criteria-based rules. Use them to organize your fleet by region, device type, manufacturer, or any combination of attributes.
Collection object
{
"id": "col_abc123def456",
"name": "Northeast EV Fleet",
"collectionType": "DEVICE",
"description": "All EV devices in the northeast region",
"criteria": {
"rule": {
"attribute": "deviceType",
"operator": "EQUALS",
"value": "VEHICLE"
}
},
"workspaceId": "ws_abc123def456",
"dynamic": true,
"isActive": true,
"createdAt": "2025-06-01T00:00:00.000Z",
"updatedAt": "2025-06-01T00:00:00.000Z"
}Collection types
| Type | Description |
|---|---|
DEVICE | Group of devices |
SITE | Group of sites |
CUSTOMER | Group of customers |
Criteria rules
Collections use a composable criteria system. A criteria object can contain:
rule— a single filter conditionand— an array of criteria objects (all must match)or— an array of criteria objects (any must match)
Operators
| Operator | Description |
|---|---|
EQUALS | Exact match |
NOT_EQUALS | Does not match |
IN | Matches any value in the list |
Example: single rule
{
"rule": {
"attribute": "deviceType",
"operator": "EQUALS",
"value": "VEHICLE"
}
}Example: compound criteria
{
"and": [
{
"rule": {
"attribute": "deviceType",
"operator": "EQUALS",
"value": "VEHICLE"
}
},
{
"rule": {
"attribute": "manufacturer",
"operator": "IN",
"value": ["TESLA", "RIVIAN"]
}
}
]
}List collections
GET /v1/collections
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
perPage | integer | 20 | Items per page |
collectionType | enum | — | Filter by type: DEVICE, SITE, or CUSTOMER |
Response: 200 OK — Paginated list of collection objects.
Get collection
GET /v1/collections/:id
Response: 200 OK — Returns the collection object.
Get collection entities
List the entities (devices, sites, or customers) belonging to a collection.
GET /v1/collections/:id/entities
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
perPage | integer | 20 | Items per page |
Response: 200 OK
{
"data": [
{
"id": "dev_abc123def456",
"name": "My EV",
"deviceType": "VEHICLE",
"workspaceId": "ws_abc123def456",
"manufacturer": "TESLA"
}
],
"meta": {
"total": 42,
"page": 1,
"perPage": 20
}
}Create collection
POST /v1/collections
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Collection name (min 1 character) |
collectionType | enum | Yes | DEVICE, SITE, or CUSTOMER |
description | string | No | Optional description |
criteria | object | Yes | Filter criteria (see Criteria Rules) |
{
"name": "Northeast EV Fleet",
"collectionType": "DEVICE",
"description": "All EV devices in the northeast region",
"criteria": {
"rule": {
"attribute": "deviceType",
"operator": "EQUALS",
"value": "VEHICLE"
}
}
}Response: 201 Created — Returns the created collection object.
Update collection
PATCH /v1/collections/:id
All fields are optional — provide at least one.
| Field | Type | Description |
|---|---|---|
name | string | New name |
description | string | New description |
dynamic | boolean | Whether the collection uses live queries |
isActive | boolean | Whether the collection is actively maintained |
visibility | enum | INTERNAL or SHARED |
criteria | object | New filter criteria |
Response: 200 OK — Returns the updated collection object.
Delete collection
DELETE /v1/collections/:id
Response: 204 No Content
Share collection
Share a collection with another organization.
POST /v1/collections/:id/share
| Field | Type | Required | Description |
|---|---|---|---|
recipientOrgEmail | string | Yes | Email identifying the recipient organization |
{
"recipientOrgEmail": "partner@example.com"
}Response: 200 OK