Temporal

The history of what devices have reported, as opposed to their current values. A series is one property of one device, identified by tags — deviceId, serviceId, and on array properties the element index, since each element is stored as its own point. Values come back as parallel t/v arrays rather than one object per point.

Current values come from the flake module, names, units and display formats for the raw ids from the schema module. Nothing here emits events — the recorded ones come from other modules, and live changes arrive as OBJECT_UPDATED over the websocket. Worked requests and responses: Historical Data.

POST	Query historical series/api/v1/temporal/query
GET	List stored series/api/v1/temporal/schema
POST	Query recorded events/api/v1/temporal/events
GET	Read one property's history/api/v1/temporal/devices/:deviceId/properties/:propertyId
POST	Bulk-import history (migration)/api/v1/temporal/import

Query historical series

Reads many series at once — several properties, devices and services — with automatic downsampling toward maxPoints. The route chart views should use.

POST/api/v1/temporal/query

Body

Name	Description
propertiesarraystring	The properties in play: in a service listing their current values, added from depth 1; in a history query the ids to read — at least one, because every property is stored as its own series.
devicesarraystringoptional	Restrict to these devices. Omit for every device the caller may read.
servicesarraystringoptional	The services in play: in a device listing the device's own services, added from depth 1; in a history query the service identifiers the read is narrowed to.
valueClassoptionalenum	Restrict the read to one storage family. Omit to read whichever families hold the requested properties — a request covering both is answered by one statement per family and costs one extra scan. Set it only to rule a family out. Possible values: numeric, text
fromintegeroptional	Start of the range, epoch milliseconds. Defaults to an hour before to. min 0
tointegeroptional	Recipient address when sending a mail; on a history query the end of the range instead, in UTC epoch milliseconds, defaulting to now. min 0
orderoptionalenum	Output order of each series. Default: asc Possible values: asc, desc
boundarybooleanoptional	Also return each series' newest point before from, so a step-shaped chart can start at the window edge instead of at the first in-range sample. Requires an explicit devices list; series count and lookback are capped. Default: false
boundaryLookbackintegeroptional	How far before from the boundary scan may reach, in milliseconds. Size it from the property's lastUpdate when known; defaults and caps are server-side. > 0
limitintegeroptional	Maximum points per series. Default: 5000 > 0 · max 50000
maxPointsintegeroptional	Target points per series. A range that would exceed it is bucketed automatically. Set to 0 to opt out and receive raw points. Default: 2000 min 0
intervalintegeroptional	Explicit bucket width in milliseconds. Disables automatic downsampling. > 0
fnoptionalenum	How points within a bucket are combined. Only meaningful with interval. Possible values: avg, sum, min, max, count, first, last
groupByarrayoptional	Tags that identify a series. Defaults to deviceId + serviceId + index; index matters because an array property writes one point per element.

Response

Name	Description
fromnumber	Start of the range, epoch milliseconds. Defaults to an hour before to.
tonumber	Recipient address when sending a mail; on a history query the end of the range instead, in UTC epoch milliseconds, defaulting to now.
intervalnumberoptional	Explicit bucket width in milliseconds. Disables automatic downsampling.
seriesarray	One series: parallel arrays rather than one object per point.
mstring	The property this series belongs to. Pattern: ^0x[0-9A-Fa-f]{4}$
keydictionary	Tag values identifying the series. A tag the series carries no value for is omitted rather than sent as null, so groupBy bounds which keys can appear, not which ones do — index is present only on array properties, holding the element position. Values are strings even when they read as numbers.
typeenum	How to read v. A boolean series returns true/false, except when the request spans several storage types or aggregates, where it is 1/0. Possible values: number, boolean, string
ninteger	Points matching before limit was applied — greater than t.length means truncated.
tarraynumber	Timestamps in epoch milliseconds, index-aligned with v.
v	Values, index-aligned with t.
Alternative 1array	Values, index-aligned with t.
Alternative 2array	Values, index-aligned with t.
Alternative 3array	Values, index-aligned with t.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
400	The query is malformed; message names the field to fix.	message: string
400	The query would scan more than the server allows — narrow the range, devices or properties; message names the knob to turn.	message: string
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

List stored series

Which properties actually have stored history in this tenant, and how to read their values.

GET/api/v1/temporal/schema

Response

Name	Description
servicestring	Service the property belongs to.
propertystring	Property identifier in the form 0x00AB. Pattern: ^0x[0-9A-Fa-f]{4}$
typeenum	Discriminator of the variant that follows — which answer a device gave, which second factor was enrolled, how a stored series is to be read. Read it before the fields beside it. Possible values: number, boolean, string
declaredTypestringoptional	The device's own type name — uint16, datetime, bool. Distinguishes what type cannot: a timestamp from a plain integer.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Query recorded events

Reads recorded events, newest first by default; filter by names, devices, services and range.

POST/api/v1/temporal/events

Body

Name	Description
namesarraystringoptional	Restrict to these event names.
devicesarraystringoptional	Restrict to these devices. Omit for every device the caller may read.
servicesarraystringoptional	The services in play: in a device listing the device's own services, added from depth 1; in a history query the service identifiers the read is narrowed to.
fromintegeroptional	Start of the range, epoch milliseconds. Defaults to an hour before to. min 0
tointegeroptional	Recipient address when sending a mail; on a history query the end of the range instead, in UTC epoch milliseconds, defaulting to now. min 0
orderoptionalenum	Output order of each series. Default: desc Possible values: asc, desc
limitintegeroptional	Maximum points per series. Default: 100 > 0 · max 10000

Response

Name	Description
namestring	Name of the addressed item — a block or template, a device method, a recorded event. A method name is limited to letters, digits, _ and -, because it becomes a segment of the message CRN.
attributesdictionary	Free-form attributes recorded with the event.
tagsdictionary	String tags identifying the event's origin.
timestampnumber	When the event was recorded, UTC epoch milliseconds.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Read one property's history

One series, addressed by path, for the cases that need no body; from/to default to the last hour.

GET/api/v1/temporal/devices/Yk3pL7rWq2/properties/0x3030?order=asc&limit=5000&maxPoints=2000

Path Parameters

Name	Description
deviceIdstring	The device id, or its IMEI. min length 1
propertyIdstring	Property id in canonical hexadecimal form, e.g. 0x0800. Pattern: ^0x[0-9A-Fa-f]{4}$

Query Parameters

Name	Description
fromintegeroptional	Start of the range, epoch milliseconds. Defaults to an hour before to. min 0
tointegeroptional	Recipient address when sending a mail; on a history query the end of the range instead, in UTC epoch milliseconds, defaulting to now. min 0
orderoptionalenum	Output order of each series. Default: asc Possible values: asc, desc
limitintegeroptional	Maximum points per series. Default: 5000 > 0 · max 50000
maxPointsintegeroptional	Target points per series. A range that would exceed it is bucketed automatically. Set to 0 to opt out and receive raw points. Default: 2000 min 0
intervalintegeroptional	Explicit bucket width in milliseconds. Disables automatic downsampling. > 0
fnoptionalenum	How points within a bucket are combined. Only meaningful with interval. Possible values: avg, sum, min, max, count, first, last

Response

Name	Description
fromnumber	Start of the range, epoch milliseconds. Defaults to an hour before to.
tonumber	Recipient address when sending a mail; on a history query the end of the range instead, in UTC epoch milliseconds, defaulting to now.
intervalnumberoptional	Explicit bucket width in milliseconds. Disables automatic downsampling.
seriesarray	One series: parallel arrays rather than one object per point.
mstring	The property this series belongs to. Pattern: ^0x[0-9A-Fa-f]{4}$
keydictionary	Tag values identifying the series. A tag the series carries no value for is omitted rather than sent as null, so groupBy bounds which keys can appear, not which ones do — index is present only on array properties, holding the element position. Values are strings even when they read as numbers.
typeenum	How to read v. A boolean series returns true/false, except when the request spans several storage types or aggregates, where it is 1/0. Possible values: number, boolean, string
ninteger	Points matching before limit was applied — greater than t.length means truncated.
tarraynumber	Timestamps in epoch milliseconds, index-aligned with v.
v	Values, index-aligned with t.
Alternative 1array	Values, index-aligned with t.
Alternative 2array	Values, index-aligned with t.
Alternative 3array	Values, index-aligned with t.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
404	No device with this identifier in the tenant.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Bulk-import history (migration)

Temporary migration route: writes historical points in bulk, columnar per series. Nothing else writes history through the API — it is a by-product of devices reporting.

POST/api/v1/temporal/import

Body

Name	Description
deviceIdstring	The device id, or its IMEI. min length 1
seriesarray	One series: parallel arrays rather than one object per point.
serviceIdstring	Service the property belongs to. min length 1
namestring	Property the series belongs to, as 0x00AB. Pattern: ^0x[0-9A-Fa-f]{4}$
storageenum	Which storage table the points land in. Possible values: float, int, bool
typestringoptional	How to read v. A boolean series returns true/false, except when the request spans several storage types or aggregates, where it is 1/0. min length 1
tarrayinteger	Timestamps in epoch milliseconds, index-aligned with v.
varray	Values, index-aligned with t.

Response

Name	Description
pointsinteger	Points accepted and flushed to the store.

Errors

Status	Description	Body
403	You do not have permission to perform this action
409	A tenant with the given name already exists	code: IAM_TENANT_CONFLICT_ERROR
404	No device with this identifier in the tenant.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---