Telemetry Module

Overview

Swagger-driven developer documentation for telemetry query endpoints and contracts.

Telemetry ingest and query APIs

Key APIs

Method	Path	Summary
GET	`/api/devices/{deviceId}/telemetry/latest`	Get latest telemetry snapshot for one device
GET	`/api/devices/{deviceId}/telemetry/range`	Get telemetry time range for one device
GET	`/api/telemetry/keys`	Get all tenant telemetry keys
POST	`/api/v1/{deviceToken}/telemetry`	Device token API: ingest telemetry
POST	`/api/v1/telemetry/query`	Query telemetry for one or many devices (time range + aggregation)

Frontend Usage Flow

Frontend list pages call collection GET endpoints to load tables or summary views.
Detail pages call parameterized GET endpoints to load a single resource before rendering tabs, forms, or detail sections.
Create forms submit payloads to POST endpoints and then refresh the list or navigate to the created resource.

GET `/api/devices/{deviceId}/telemetry/latest`

Summary: Get latest telemetry snapshot for one device

Operation ID: TelemetryController_latest

Tags: Telemetry

Security:

bearer

Parameters

Name	In	Required	Type	Description
deviceId	path	yes	string	Device identifier

Responses

200

Latest telemetry snapshot returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "deviceId": {
      "type": "string"
    },
    "values": {
      "type": "object"
    },
    "ts": {
      "type": "number"
    }
  }
}

Example:

json

{
  "deviceId": "device-123",
  "values": {
    "temperature": 25.5,
    "humidity": 62
  },
  "ts": 1712486400000
}

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

GET `/api/devices/{deviceId}/telemetry/range`

Summary: Get telemetry time range for one device

Operation ID: TelemetryController_getRange

Tags: Telemetry

Security:

bearer

Parameters (2)

Name	In	Required	Type	Description
deviceId	path	yes	string	Device identifier
from	query	yes	string	Start timestamp (epoch ms)
to	query	yes	string	End timestamp (epoch ms)
aggregation	query	no	string	Aggregation mode
maxDataPoints	query	no	string	Maximum points to return

Responses (2)

200 (2)

Telemetry range returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TelemetryDeviceSeriesDto"
      }
    },
    "from": {
      "type": "number"
    },
    "to": {
      "type": "number"
    },
    "aggregation": {
      "type": "string"
    }
  }
}

Example:

json

{
  "data": [
    {
      "deviceId": "device-123",
      "series": [
        {
          "key": "temperature",
          "points": [
            {}
          ]
        }
      ]
    }
  ],
  "from": 1712400000000,
  "to": 1712486400000,
  "aggregation": "avg"
}

400

Invalid time range

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "statusCode",
    "error"
  ],
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "error": {
      "type": "string"
    },
    "message": {
      "type": "object"
    }
  }
}

Example:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid time range"
}

401 (2)

Unauthorized

No response body.

Notes / Constraints (2)

This endpoint depends on one or more path parameters.
This endpoint accepts query parameters that can affect filtering, pagination, or lookup behavior.
Swagger declares security requirements for this operation.

GET `/api/telemetry/keys`

Summary: Get all tenant telemetry keys

Operation ID: TelemetryController_getTelemetryKeys

Tags: Telemetry

Security:

bearer

Responses (3)

200 (3)

Telemetry keys returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/TelemetryKeyDto"
  }
}

Example:

json

[
  {
    "key": "temperature"
  }
]

401 (3)

Unauthorized

No response body.

Notes / Constraints (3)

Swagger declares security requirements for this operation.

POST `/api/v1/{deviceToken}/telemetry`

Summary: Device token API: ingest telemetry

Operation ID: TelemetryController_ingest

Tags: Telemetry

Parameters (3)

Name	In	Required	Type	Description
deviceToken	path	yes	string	Device access token

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "payload": {
      "type": "object",
      "description": "Arbitrary telemetry payload sent by the device"
    }
  }
}

Example:

json

{
  "payload": {
    "temperature": 25.5,
    "humidity": 62,
    "pressure": 1.02,
    "battery": 87,
    "ts": "2026-04-07T12:00:00.000Z"
  }
}

Responses (4)

200 (4)

Telemetry ingested successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "success": true
}

400 (2)

Invalid telemetry payload

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "statusCode",
    "error"
  ],
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "error": {
      "type": "string"
    },
    "message": {
      "type": "object"
    }
  }
}

Example:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid time range"
}

Notes / Constraints (4)

This endpoint depends on one or more path parameters.
Supported request content types: application/json.

POST `/api/v1/telemetry/query`

Summary: Query telemetry for one or many devices (time range + aggregation)

Operation ID: TelemetryController_queryTelemetry

Tags: Telemetry

Security:

bearer

Request (2)

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "deviceIds",
    "from",
    "to"
  ],
  "properties": {
    "deviceIds": {
      "type": "array",
      "description": "One or more device IDs",
      "items": {
        "type": "string"
      }
    },
    "keys": {
      "type": "array",
      "description": "Telemetry keys to include (empty = all keys)",
      "items": {
        "type": "string"
      }
    },
    "from": {
      "type": "number",
      "description": "Start timestamp (epoch ms)"
    },
    "to": {
      "type": "number",
      "description": "End timestamp (epoch ms)"
    },
    "aggregation": {
      "type": "string",
      "enum": [
        "none",
        "min",
        "max",
        "avg",
        "sum",
        "count"
      ]
    },
    "maxDataPoints": {
      "type": "number",
      "description": "Maximum points to return"
    }
  }
}

Example:

json

{
  "deviceIds": [
    "device-1",
    "device-2"
  ],
  "keys": [
    "temperature",
    "humidity"
  ],
  "from": 1712400000000,
  "to": 1712486400000,
  "aggregation": "avg",
  "maxDataPoints": 500
}

Responses (5)

200 (5)

Telemetry query returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TelemetryDeviceSeriesDto"
      }
    },
    "from": {
      "type": "number"
    },
    "to": {
      "type": "number"
    },
    "aggregation": {
      "type": "string"
    }
  }
}

Example:

json

{
  "data": [
    {
      "deviceId": "device-123",
      "series": [
        {
          "key": "temperature",
          "points": [
            {}
          ]
        }
      ]
    }
  ],
  "from": 1712400000000,
  "to": 1712486400000,
  "aggregation": "avg"
}

400 (3)

Invalid telemetry query payload

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "statusCode",
    "error"
  ],
  "properties": {
    "statusCode": {
      "type": "number"
    },
    "error": {
      "type": "string"
    },
    "message": {
      "type": "object"
    }
  }
}

Example:

json

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid time range"
}

401 (4)

Unauthorized

No response body.

Notes / Constraints (5)

Supported request content types: application/json.
Swagger declares security requirements for this operation.

Module Notes / Constraints

Generated from OpenAPI version metadata: 1.0.
4 operation(s) in this module declare explicit Swagger security requirements.
HTTP methods present in this module: GET, POST.
This file is generated from Swagger/OpenAPI and should be regenerated when controller, DTO, or Swagger decorator changes affect the spec.

Telemetry Module ​

Overview ​

Key APIs ​

Frontend Usage Flow ​

GET /api/devices/{deviceId}/telemetry/latest ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

GET /api/devices/{deviceId}/telemetry/range ​

Parameters (2) ​

Responses (2) ​

200 (2) ​

400 ​

401 (2) ​

Notes / Constraints (2) ​

GET /api/telemetry/keys ​

Responses (3) ​

200 (3) ​

401 (3) ​

Notes / Constraints (3) ​

POST /api/v1/{deviceToken}/telemetry ​

Parameters (3) ​

Request ​

Responses (4) ​

200 (4) ​

400 (2) ​

Notes / Constraints (4) ​

POST /api/v1/telemetry/query ​

Request (2) ​

Responses (5) ​

200 (5) ​

400 (3) ​

401 (4) ​

Notes / Constraints (5) ​

Module Notes / Constraints ​

Telemetry Module

Overview

Key APIs

Frontend Usage Flow

GET `/api/devices/{deviceId}/telemetry/latest`

Parameters

Responses

200

401

Notes / Constraints

GET `/api/devices/{deviceId}/telemetry/range`

Parameters (2)

Responses (2)

200 (2)

400

401 (2)

Notes / Constraints (2)

GET `/api/telemetry/keys`

Responses (3)

200 (3)

401 (3)

Notes / Constraints (3)

POST `/api/v1/{deviceToken}/telemetry`

Parameters (3)

Request

Responses (4)

200 (4)

400 (2)

Notes / Constraints (4)

POST `/api/v1/telemetry/query`

Request (2)

Responses (5)

200 (5)

400 (3)

401 (4)

Notes / Constraints (5)

Module Notes / Constraints