Skip to content
SENS Platform Docs

Telemetry API Contract V1

Status

Section titled “Status”

Available for one-Device current snapshots and bounded history:

GET /v1/devices/{deviceId}/current-values

GET /v1/devices/{deviceId}/measurements

Both routes require telemetry:read. The current-values route applies current Device visibility and returns every active Device-Type field. A field has currentValue: null until its Flow stores the first value. The measurements route returns normalized history for one currently visible Device. Tenant- or organization-invisible Devices are returned as 404 to avoid existence leaks.

Historical query

Section titled “Historical query”

from and to are required ISO timestamps. from is inclusive, to is exclusive, from must precede to, and one request may cover at most exactly 30 days. Optional repeated measurementKey parameters accept at most 25 keys. limit defaults to and is capped at 5,000.

Rows are ordered by observedAt descending and then measurementId descending. nextCursor, when present, is an opaque continuation for this stable tuple. Empty windows return 200 with an empty measurements array. Invalid timestamps, ranges, filters, limits, and cursors return 400.

Only the current replay revision is returned and tombstones are omitted. Imported or older measurements that predate revision heads remain visible. Optional deviceTypeId and deviceFieldDefinitionId identities keep fields from an earlier Device Type separate from the current field catalog.

Purpose

Section titled “Purpose”

The Telemetry API allows authorized users and API clients to query normalized measurement data.

Requirements

Section titled “Requirements”

The API must support:

  • Tenant-scoped access.
  • Organization-scoped access.
  • Device filtering.
  • Time range filtering.
  • Measurement key filtering.
  • Pagination or bounded result limits.
  • Safe error responses.
  • Correlation IDs.
  • Authorization checks.

Query constraints

Section titled “Query constraints”

Unbounded queries are not allowed.

The reusable TelemetryQueryRequestDto requires:

  • tenantId
  • from
  • to

The implemented Device-history route applies the stricter limits described above. Large or longer-range retrievals belong to future asynchronous export jobs instead of synchronous API responses.

TypeScript DTOs

Section titled “TypeScript DTOs”

The DTO names are:

  • TelemetryQueryRequestDto
  • TelemetryQueryResponseDto
  • TelemetryMeasurementDto
  • MeasurementValue
  • MeasurementValueType

MeasurementValueType currently allows:

  • gauge
  • counter
  • status
  • event

TelemetryQueryResponseDto contains measurements and an optional nextCursor. Runtime schemas validate the response used by the web console and are synchronized with OpenAPI.

Security

Section titled “Security”

The API enforces:

  • Authentication.
  • Tenant authorization.
  • Organization authorization.
  • Device visibility.
  • Historical organization scope at each measurement’s stored organizationUnitId against the caller’s currently effective grants.

Platform and tenant administrators can read tenant-wide measurements, including historically unassigned values. Organization users receive only measurements whose historical organization lies in their allowed subtree. A later Device move therefore does not reveal earlier telemetry from another organization.

Load boundary

Section titled “Load boundary”

V1 adds no route-specific rate limiter. Authentication, the 30-day window, the 5,000-row page cap, opaque pagination, and the dashboard’s lack of automatic Timeseries polling provide the initial boundary. This decision must be revisited if production metrics show abusive or expensive query patterns.