Generic endpoints

Most object types share a set of generic endpoints. Endpoints that act on a whole object type take the plural form of the type name, those that act on one object the singular form; see Object types and their plural form.

Get multiple objects

Retrieves the objects of a type, optionally filtered, sorted, paged and trimmed to selected fields.

Operation: READ

GET /v1/{tenant}/{objectTypePlural}

TIP

Notice the plural form of the object type.

Parameter	Description
q	A query to filter, sort, page and select. See the query language
p	An ISO 8601 timestamp. Objects not updated since this time are returned with their metadata only, marked "partial": true. Used to poll for changes without transferring every object in full on every call

Returns an array of objects in the form of the base object, or of the fields selected with select(…).

Get a single object

Retrieves a single object by name or id. Both are unique, so either identifies the object.

Operation: READ

GET /v1/{tenant}/{objectType}/{nameOrId}

The endpoint takes no query parameters. To read only some fields of one object, use Get multiple objects with a name filter: q=and(eq(name,{name}),select(…)).

Returns the object matching the name or id.

Create an object

Operation: CREATE

PUT /v1/{tenant}/{objectType}/{name}

The name of the new object is given in the path; the body sets its mutable data:

{
  "mutable": {
    "customProperties": {
      "foo": "bar",
      "x": 1
    }
  }
}

Returns the object created.

Update an object

Operation: UPDATE

POST /v1/{tenant}/{objectType}/{nameOrId}

Unlike PUT, the body of a POST contains the mutable data directly. It is merged into the data already present, so to change a single property only that property needs to be sent:

{
  "customProperties": {
    "description": "Moved to stand B12"
  }
}

Returns the updated object.

Delete an object

Operation: DELETE

DELETE /v1/{tenant}/{objectType}/{nameOrId}

Returns a confirmation:

{
  "status": "OK",
  "message": "[foo] deleted from [assets]"
}

Rename an object

Changes the name of an object. Its id stays the same.

Operation: UPDATE

PATCH /v1/{tenant}/{objectType}/{id}/rename/{newName}

Remove a value from an array

Removes a value from an array property of every object that holds it, without rewriting the rest of the objects.

Operation: UPDATE

PATCH /v1/{tenant}/{objectTypePlural}/pull/{arrayPropertyPath}/{value}

Parameter	Description
q	Narrows down the objects to change. See the query language

Object history

Every change to every object is kept. The history endpoint returns the previous versions of the objects of a type, over a time window.

Operation: READ on the object type's history, for example assets.history

GET /v1/{tenant}/{objectTypePlural}/history?q={query}

Parameter	Description
q	Required. Selects the objects and the time window. See the query language

The query selects the object by name with eq(name,…) and the time window with gt and le on metadata.updatedTime. This combination is indexed and answers quickly at any size of history; always give both. Entries are returned in chronological order, and select(…) limits the fields returned per entry. The history of one asset over five minutes:

GET /v1/{tenant}/assets/history?q=and(eq(name,TRL-0412),gt(metadata.updatedTime,2026-10-05T12:00:00.000Z),le(metadata.updatedTime,2026-10-05T12:05:00.000Z))

Returns an array of previous versions of the objects, each with the time of the change in metadata.updatedTime and the user or process that made it in metadata.updatedBy.

Object values

Returns the distinct values of a property and how often each occurs. With several properties, every combination is returned.

Operation: READ

GET /v1/{tenant}/{objectTypePlural}/values/{property}
GET /v1/{tenant}/{objectTypePlural}/values/{property}/{property}/...

The property is given as its path in dot notation, for example mutable.customProperties.group.

Parameter	Description
q	Selects the objects to include. See the query language

Returns the values with their counts:

{
  "property": "mutable.customProperties.group",
  "values": [
    { "Terminal": 11 },
    { "Non-motorised": 22 },
    { "Motorised": 25 }
  ]
}

Object aggregates

Counts the objects that have a custom property set, or sums a numeric custom property.

Operation: READ

GET /v1/{tenant}/{objectTypePlural}/aggregate/{customProperty}/{count|sum}

The property is the name of a property in mutable.customProperties.

Parameter	Description
q	Selects the objects to include. See the query language

Returns a single number.

Object type schema

Returns the JSON Schema the tenant has configured for an object type. It defines the fields of mutable, their types and allowed values, and which fields are required; every write is validated against it.

Operation: READ

GET /v1/{tenant}/{objectTypePlural}/schema

Returns the JSON Schema of the object type. An object type without a configured schema answers with an error.