Ontology

The Ontology consists of platform primitives which are configured to fit the exact shape and schema of your data: from the types of devices you have and the data they produce to transactions and integrations your workflows are composed of.

The typical starting primitives to onboard are the ones which represent the hardware types and data signals associated to those types:

Thing types define a kind of device: which metrics it reports and which properties it carries. They're versioned.
Metric definitions define a single measurement: its data type, unit, and default aggregation. Metrics are reused across many thing types.

The Ontology page has three tabs: a relationship graph (thing types linked to the metrics they include), metric definitions, and thing type definitions.

This page describes managing the ontology in the console. For the concepts behind it (how thing types reference metrics, how properties and versioning work, and metric reuse), see Data model.

Thing types

A thing type has a stable identity (the index, tdefi_) that points at its latest version (tdef_) and keeps the full version history. A device binds to a specific version, which fixes the metric set and property schema that apply to it.

Fields

Field	Type	Required	Notes
Display name	string (1–100)	Yes
Description	string (0–500)	No
Metric ids	list	Yes	The metrics this version reports
Property definitions	list	No	Typed property schema (see below)
Model metadata	object	No	Manufacturer, model, hardware revision, certifications, and more
Tags	list	No
Default image / icon URL	URL	No	Index-level visual assets

Versioning

Each version is a full snapshot. You change the metric set by creating a new version, not by editing an existing one. The "create version" form pre-fills every field from the latest version. A response also reports deletedMetricIds: metrics that earlier versions had but this one dropped.

When updating an existing version, you can change its display name, description, tags, model metadata, and property definitions, but not its metric ids.

Metric definitions

A metric definition (surfaced as metricId) describes one measurement.

Field	Type	Required	Mutable	Notes
Name	string	Yes	No	Programmatic name; fixed after creation
Data type	enum	Yes	No	See below
Default aggregation	enum	Yes	No	See below
Display name	string	No	Yes
Description	string	No	Yes
Unit label	string	No	Yes
Tags	list	No	Yes
Enum values	list	No	Yes	Only valid when the data type is `Int`

Data types

Data type	Notes
`Int`	Integer
`Double`	Floating point
`String`	Text
`Bool`	Boolean
`Json`	JSON document

There's no separate "enum" data type. An enum metric is an Int with a non-empty list of enum values, each mapping an integer code to a name (plus optional display name and description). Codes are append-only and unique; names are required and unique.

Aggregations

defaultAggregation is how the metric is combined when binned.

Data type	Allowed aggregations
`Int`, `Double`	`First`, `Last`, `Sum`, `Min`, `Max`, `Avg`, `Count`
`String`, `Bool`, `Json`	`First`, `Last`, `Count`
Enum (`Int` + enum values)	`First`, `Last`, `Count`

Arithmetic aggregations are disallowed for enums, since the codes have no numeric meaning.

Property definitions

Properties are typed, predefined attributes a device of this type carries (for example a battery's capacity). Each property has:

Field	Type	Required	Notes
Name	string	Yes
Value type	enum	Yes	`string`, `int`, `double`, `bool`
Description	string	No
Unit	string	No
Constraints	list	No	Validation rules (see below)

A constraint is an operator plus a value. Operators: >, >=, <, <=, ==, !=.

When updating a version, omitting propertyDefinitions leaves them unchanged; passing a list replaces them entirely; passing an empty list removes them all.

States

Lifecycle status: list endpoints take status = active (default), deleted, or all. Deletes are soft, so entities carry an isDeleted flag.
Graph layouts: the relationship graph renders as bipartite (default), galaxy, or force.

API

Send your API key in the X-Api-Key header. Reads need a read scope; create, update, and delete need write. Ids: thing-type index tdefi_, thing-type version tdef_, metric mdef_. These are version 2 endpoints. The thing-type endpoints are also in the API Reference tab.

Thing types

Method	Path	Purpose
`GET`	`/v2/definitions/thing-types`	List thing types (paginated)
`POST`	`/v2/definitions/thing-types`	Create a thing type (its first version)
`GET`	`/v2/definitions/thing-types/{thingTypeId}`	Get one thing type
`PUT`	`/v2/definitions/thing-types/{thingTypeId}`	Update index metadata
`DELETE`	`/v2/definitions/thing-types/{thingTypeId}`	Soft-delete a thing type
`GET`	`/v2/definitions/thing-types/{thingTypeId}/versions`	List version history
`POST`	`/v2/definitions/thing-types/{thingTypeId}/versions`	Create a new version
`GET`	`/v2/definitions/thing-types/versions/{thingTypeDefId}`	Get one version (`?includeMetricDefinitions=true` resolves metrics)

Metric definitions

Method	Path	Purpose
`GET`	`/v2/definitions/metrics`	List metrics (paginated)
`GET`	`/v2/definitions/metrics/{metricId}`	Get one metric
`POST`	`/v2/definitions/metrics`	Create a metric
`PUT`	`/v2/definitions/metrics/{metricId}`	Update mutable fields
`DELETE`	`/v2/definitions/metrics/{metricId}`	Soft-delete a metric