Devices Module

Overview

Swagger-driven developer documentation for device management endpoints and contracts.

Key APIs

Method	Path	Summary
GET	`/api/devices`	List devices
POST	`/api/devices`	Create device
GET	`/api/devices/{deviceId}/keys`	DevicesController_getDeviceTelemetryKeys
DELETE	`/api/devices/{id}`	Delete device
GET	`/api/devices/{id}`	Get device details
PATCH	`/api/devices/{id}`	Update device
GET	`/api/devices/{id}/attributes`	Get device attributes
POST	`/api/devices/{id}/attributes`	Save device attributes
POST	`/api/devices/{id}/commands`	Send command to device
POST	`/api/devices/{id}/test-ack`	Send test command ACK
POST	`/api/devices/{id}/test-telemetry`	Send test telemetry
POST	`/api/devices/bulk/import`	DevicesBulkController_import
GET	`/api/devices/bulk/template.csv`	DevicesBulkController_downloadTemplate
POST	`/api/devices/bulk/validate`	DevicesBulkController_validate
GET	`/api/devices/keys`	Get all telemetry keys
GET	`/api/devices/type-defaults/{deviceType}`	Get default dashboard for device type
GET	`/api/devices/types`	Get device types

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.
Edit flows load existing values, submit to PUT or PATCH endpoints, and then refresh the visible state.
Delete actions call DELETE endpoints and then refresh collection state.

GET `/api/devices`

Summary: List devices

Operation ID: DevicesController_findAll

Tags: Devices

Security:

bearer

Responses

200

Content-Type: application/json

Schema:

json

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

Example:

json

[
  {
    "deviceId": "string",
    "name": "string",
    "deviceType": "string",
    "assetId": "string"
  }
]

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

POST `/api/devices`

Summary: Create device

Operation ID: DevicesController_create

Tags: Devices

Security:

bearer

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "name",
    "deviceType"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "deviceType": {
      "type": "string"
    },
    "assetId": {
      "type": "string"
    },
    "profileId": {
      "type": "string",
      "description": "Device profile id"
    },
    "role": {
      "type": "string",
      "description": "Logical device role",
      "enum": [
        "DEVICE",
        "GATEWAY"
      ]
    },
    "type": {
      "type": "string",
      "description": "Backward-compatible alias for role",
      "enum": [
        "DEVICE",
        "GATEWAY"
      ]
    },
    "inactivityTimeoutMs": {
      "type": "number",
      "description": "Inactivity timeout in milliseconds"
    },
    "targetDashboardId": {
      "type": "string",
      "description": "Target dashboard id"
    },
    "targetStateId": {
      "type": "string",
      "description": "Target dashboard state id"
    },
    "applyToAllOfType": {
      "type": "boolean",
      "description": "Apply dashboard/state defaults to all devices of the same type"
    },
    "commandTransport": {
      "type": "string",
      "enum": [
        "WS",
        "MQTT"
      ]
    }
  }
}

Example:

json

{
  "name": "Boiler Sensor",
  "deviceType": "temperature-sensor",
  "assetId": "asset-123",
  "profileId": "default",
  "role": "DEVICE",
  "type": "DEVICE",
  "inactivityTimeoutMs": 300000,
  "targetDashboardId": "dashboard-123",
  "targetStateId": "default",
  "applyToAllOfType": false,
  "commandTransport": "WS"
}

Responses

201

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "deviceId",
    "name",
    "deviceType"
  ],
  "properties": {
    "deviceId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "deviceType": {
      "type": "string"
    },
    "assetId": {
      "type": "string"
    }
  }
}

Example:

json

{
  "deviceId": "string",
  "name": "string",
  "deviceType": "string",
  "assetId": "string"
}

401

Unauthorized

No response body.

Notes / Constraints

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

GET `/api/devices/{deviceId}/keys`

Operation ID: DevicesController_getDeviceTelemetryKeys

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
deviceId	path	yes	string	-

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

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

DELETE `/api/devices/{id}`

Summary: Delete device

Operation ID: DevicesController_delete

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Responses

200

No response body.

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/{id}`

Summary: Get device details

Operation ID: DevicesController_findOne

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

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

PATCH `/api/devices/{id}`

Summary: Update device

Operation ID: DevicesController_update

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "deviceType": {
      "type": "string"
    },
    "assetId": {
      "type": "string"
    },
    "profileId": {
      "type": "string",
      "description": "Device profile id"
    },
    "role": {
      "type": "string",
      "description": "Logical device role",
      "enum": [
        "DEVICE",
        "GATEWAY"
      ]
    },
    "type": {
      "type": "string",
      "description": "Backward-compatible alias for role",
      "enum": [
        "DEVICE",
        "GATEWAY"
      ]
    },
    "inactivityTimeoutMs": {
      "type": "number",
      "description": "Inactivity timeout in milliseconds"
    },
    "targetDashboardId": {
      "type": "string",
      "description": "Target dashboard id"
    },
    "targetStateId": {
      "type": "string",
      "description": "Target dashboard state id"
    },
    "applyToAllOfType": {
      "type": "boolean",
      "description": "Apply dashboard/state defaults to all devices of the same type"
    }
  }
}

Example:

json

{
  "name": "Updated Device Name",
  "deviceType": "temperature-sensor",
  "assetId": "asset-123",
  "profileId": "default",
  "role": "DEVICE",
  "type": "DEVICE",
  "inactivityTimeoutMs": 300000,
  "targetDashboardId": "dashboard-123",
  "targetStateId": "default",
  "applyToAllOfType": false
}

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Supported request content types: application/json.
Swagger declares security requirements for this operation.

GET `/api/devices/{id}/attributes`

Summary: Get device attributes

Operation ID: DevicesController_getAttributes

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

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

POST `/api/devices/{id}/attributes`

Summary: Save device attributes

Operation ID: DevicesController_saveAttributes

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "scope",
    "attributes"
  ],
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "SERVER",
        "SHARED",
        "CLIENT"
      ]
    },
    "attributes": {
      "type": "object"
    }
  }
}

Example:

json

{
  "scope": "SERVER",
  "attributes": {
    "temperature": 25
  }
}

Responses

201

No response body.

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Supported request content types: application/json.
Swagger declares security requirements for this operation.

POST `/api/devices/{id}/commands`

Summary: Send command to device

Operation ID: DevicesController_sendCommand

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "channel": {
      "type": "number"
    },
    "state": {
      "type": "number"
    },
    "key": {
      "type": "string"
    },
    "value": {
      "type": "number"
    },
    "retries": {
      "type": "number"
    },
    "retryIntervalMs": {
      "type": "number"
    },
    "method": {
      "type": "string"
    },
    "params": {
      "type": "object"
    },
    "requestId": {
      "type": "string"
    },
    "command": {
      "type": "object"
    }
  }
}

Example:

json

{
  "type": "set_numeric_value",
  "channel": 1,
  "state": 1,
  "key": "volume",
  "value": 50,
  "retries": 2,
  "retryIntervalMs": 1000,
  "method": "reboot",
  "params": {},
  "requestId": "rpc_1234",
  "command": {}
}

Responses

201

No response body.

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Supported request content types: application/json.
Swagger declares security requirements for this operation.

POST `/api/devices/{id}/test-ack`

Summary: Send test command ACK

Operation ID: DevicesController_sendTestAck

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "channel": {
      "type": "number"
    },
    "state": {
      "type": "number"
    },
    "key": {
      "type": "string"
    },
    "value": {
      "type": "object"
    },
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "ts": {
      "type": "number"
    }
  }
}

Example:

json

{
  "requestId": "cmd_123",
  "channel": 1,
  "state": 1,
  "key": "volume",
  "value": 75,
  "success": true,
  "message": "channel updated",
  "ts": 1713270000000
}

Responses

201

No response body.

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Supported request content types: application/json.
Swagger declares security requirements for this operation.

POST `/api/devices/{id}/test-telemetry`

Summary: Send test telemetry

Operation ID: DevicesController_sendTestTelemetry

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
id	path	yes	string	-

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "protocol": {
      "type": "string",
      "enum": [
        "HTTP",
        "MQTT"
      ]
    },
    "payload": {
      "type": "object",
      "description": "Optional telemetry payload to ingest. If omitted, backend will generate sample telemetry."
    }
  }
}

Example:

json

{
  "protocol": "HTTP",
  "payload": {
    "temperature": 25.4,
    "gps": {
      "lat": 28.6139,
      "lon": 77.209
    },
    "ecg": [
      101,
      104,
      99,
      110
    ],
    "status": "on",
    "volume": 72
  }
}

Responses

201

No response body.

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Supported request content types: application/json.
Swagger declares security requirements for this operation.

POST `/api/devices/bulk/import`

Operation ID: DevicesBulkController_import

Tags: Devices

Security:

bearer

Responses

201

No response body.

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

GET `/api/devices/bulk/template.csv`

Operation ID: DevicesBulkController_downloadTemplate

Tags: Devices

Security:

bearer

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

POST `/api/devices/bulk/validate`

Operation ID: DevicesBulkController_validate

Tags: Devices

Security:

bearer

Responses

201

No response body.

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

GET `/api/devices/keys`

Summary: Get all telemetry keys

Operation ID: DevicesController_getAllTelemetryKeys

Tags: Devices

Security:

bearer

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

GET `/api/devices/type-defaults/{deviceType}`

Summary: Get default dashboard for device type

Operation ID: DevicesController_getTypeDashboardDefault

Tags: Devices

Security:

bearer

Parameters

Name	In	Required	Type	Description
deviceType	path	yes	string	-

Responses

200

No response body.

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/types`

Summary: Get device types

Operation ID: DevicesController_getDeviceTypes

Tags: Devices

Security:

bearer

Responses

200

No response body.

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

Module Notes / Constraints

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

Devices Module ​

Overview ​

Key APIs ​

Frontend Usage Flow ​

GET /api/devices ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

POST /api/devices ​

Request ​

Responses ​

201 ​

401 ​

Notes / Constraints ​

GET /api/devices/{deviceId}/keys ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

DELETE /api/devices/{id} ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

GET /api/devices/{id} ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

PATCH /api/devices/{id} ​

Parameters ​

Request ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

GET /api/devices/{id}/attributes ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

POST /api/devices/{id}/attributes ​

Parameters ​

Request ​

Responses ​

201 ​

401 ​

Notes / Constraints ​

POST /api/devices/{id}/commands ​

Parameters ​

Request ​

Responses ​

201 ​

401 ​

Notes / Constraints ​

POST /api/devices/{id}/test-ack ​

Parameters ​

Request ​

Responses ​

201 ​

401 ​

Notes / Constraints ​

POST /api/devices/{id}/test-telemetry ​

Parameters ​

Request ​

Responses ​

201 ​

401 ​

Notes / Constraints ​

POST /api/devices/bulk/import ​

Responses ​

201 ​

401 ​

Notes / Constraints ​

GET /api/devices/bulk/template.csv ​

Devices Module

Overview

Key APIs

Frontend Usage Flow

GET `/api/devices`

Responses

200

401

Notes / Constraints

POST `/api/devices`

Request

Responses

201

401

Notes / Constraints

GET `/api/devices/{deviceId}/keys`

Parameters

Responses

200

401

Notes / Constraints

DELETE `/api/devices/{id}`

Parameters

Responses

200

401

Notes / Constraints

GET `/api/devices/{id}`

Parameters

Responses

200

401

Notes / Constraints

PATCH `/api/devices/{id}`

Parameters

Request

Responses

200

401

Notes / Constraints

GET `/api/devices/{id}/attributes`

Parameters

Responses

200

401

Notes / Constraints

POST `/api/devices/{id}/attributes`

Parameters

Request

Responses

201

401

Notes / Constraints

POST `/api/devices/{id}/commands`

Parameters

Request

Responses

201

401

Notes / Constraints

POST `/api/devices/{id}/test-ack`

Parameters

Request

Responses

201

401

Notes / Constraints

POST `/api/devices/{id}/test-telemetry`

Parameters

Request

Responses

201

401

Notes / Constraints

POST `/api/devices/bulk/import`

Responses

201

401

Notes / Constraints

GET `/api/devices/bulk/template.csv`