{ "openapi": "3.0.4", "info": { "title": "Nastec REMO API", "description": "This document provides a complete specification of all publicly exposed APIs for the Remo project.\n\nThe APIs enable secure and efficient communication with remote IoT and mobile devices via MQTT, allowing users to authenticate using an API Key and access data related to their devices.\n\nThe following sections include detailed endpoint descriptions, request formats, and response structures, along with the technical information required for seamless integration.", "contact": { "name": "Nastec S.r.l.", "url": "https://nastec.eu", "email": "info@nastec.eu" }, "version": "4.10.0.0" }, "servers": [ { "url": "https://remo.nastec.eu/api", "description": "Public API URL" } ], "paths": { "/alarms": { "get": { "tags": [ "Alarms" ], "summary": "Retrieves alarm data from the alarms service.\nThis endpoint calls the alarms service to get current alarm information.\nNo authentication is required for this endpoint.", "responses": { "200": { "description": "Returns the alarm data successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlarmsApiResponseDto" } } } } } } }, "/alarms/keys": { "get": { "tags": [ "Alarms" ], "summary": "Retrieves the alarm keys configuration.", "responses": { "200": { "description": "Returns the alarm keys successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmKeyDto" } } } } } } } }, "/device/list": { "get": { "tags": [ "Device" ], "summary": "Retrieves a paginated list of devices based on the provided filters and pagination parameters.\nThe list is sorted by updatedAt in descending order.", "parameters": [ { "name": "page", "in": "query", "description": "Gets or sets the number of the current page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "itemsPerPage", "in": "query", "description": "Gets or sets the number of items per page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "sortBy", "in": "query", "description": "Gets or sets the type of sorting of the current page.", "schema": { "type": "string" } }, { "name": "sortByDirection", "in": "query", "description": "Gets or sets the direction of the sorting of.\nthe current page.", "schema": { "type": "string" } }, { "name": "groupMemberIds", "in": "query", "description": "Gets or sets the list of active group member IDs for filtering.\nWhen set, filters devices to include only those owned by users in this group.\nUsed in conjunction with group-based permissions to show devices accessible to group members.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "type", "in": "query", "description": "Gets or sets the device type filter to distinguish between IoT devices and smartphones.", "schema": { "type": "string", "example": "\"iot\", \"iot32\", \"smartphone\"." }, "example": "\"iot\", \"iot32\", \"smartphone\"." }, { "name": "paired", "in": "query", "description": "Gets or sets the pairing status filter to show only paired or unpaired devices.", "schema": { "type": "boolean" } }, { "name": "owner", "in": "query", "description": "Gets or sets the specific owner ID to filter devices by a single user.\nWhen set, returns devices owned by this user or where this user is a collaborator.", "schema": { "type": "string", "example": "\"user123\", \"auth0|123456789\"." }, "example": "\"user123\", \"auth0|123456789\"." }, { "name": "owners", "in": "query", "description": "Gets or sets the list of user IDs to filter devices where users are owners or collaborators.\nSupports complex permission scenarios by allowing multiple user IDs in a single filter.\nWhen combined with GroupMemberIds, uses OR logic to include devices accessible through either mechanism.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filterdUserIds", "in": "query", "description": "Gets or sets the list of user IDs that match a search query.\nThis property is populated by the controller after processing search terms\nand contains user IDs whose profiles match the search criteria.\nUsed internally to filter devices by searchable user information.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "connectionStatus", "in": "query", "description": "Gets or sets the connection status filter to show devices based on their online/offline state.\nDevices are considered online if they have connected within the last 10 minutes.", "schema": { "type": "string", "example": "\"online\", \"offline\"." }, "example": "\"online\", \"offline\"." }, { "name": "state", "in": "query", "description": "Gets or sets the device state filter.", "schema": { "type": "integer", "format": "int32" } }, { "name": "search", "in": "query", "description": "Gets or sets the generic search filter value.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "description": "Gets or sets the list of ids.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the list of devices.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceResponseDto" } } } } } } } }, "/device/list/count": { "get": { "tags": [ "Device" ], "summary": "Retrieves the count of devices based on the provided filters.", "parameters": [ { "name": "groupMemberIds", "in": "query", "description": "Gets or sets the list of active group member IDs for filtering.\nWhen set, filters devices to include only those owned by users in this group.\nUsed in conjunction with group-based permissions to show devices accessible to group members.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "type", "in": "query", "description": "Gets or sets the device type filter to distinguish between IoT devices and smartphones.", "schema": { "type": "string", "example": "\"iot\", \"iot32\", \"smartphone\"." }, "example": "\"iot\", \"iot32\", \"smartphone\"." }, { "name": "paired", "in": "query", "description": "Gets or sets the pairing status filter to show only paired or unpaired devices.", "schema": { "type": "boolean" } }, { "name": "owner", "in": "query", "description": "Gets or sets the specific owner ID to filter devices by a single user.\nWhen set, returns devices owned by this user or where this user is a collaborator.", "schema": { "type": "string", "example": "\"user123\", \"auth0|123456789\"." }, "example": "\"user123\", \"auth0|123456789\"." }, { "name": "owners", "in": "query", "description": "Gets or sets the list of user IDs to filter devices where users are owners or collaborators.\nSupports complex permission scenarios by allowing multiple user IDs in a single filter.\nWhen combined with GroupMemberIds, uses OR logic to include devices accessible through either mechanism.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filterdUserIds", "in": "query", "description": "Gets or sets the list of user IDs that match a search query.\nThis property is populated by the controller after processing search terms\nand contains user IDs whose profiles match the search criteria.\nUsed internally to filter devices by searchable user information.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "connectionStatus", "in": "query", "description": "Gets or sets the connection status filter to show devices based on their online/offline state.\nDevices are considered online if they have connected within the last 10 minutes.", "schema": { "type": "string", "example": "\"online\", \"offline\"." }, "example": "\"online\", \"offline\"." }, { "name": "state", "in": "query", "description": "Gets or sets the device state filter.", "schema": { "type": "integer", "format": "int32" } }, { "name": "search", "in": "query", "description": "Gets or sets the generic search filter value.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "description": "Gets or sets the list of ids.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the count of devices.", "content": { "application/json": { "schema": { "type": "integer", "format": "int32" } } } } } } }, "/device/export_csv": { "get": { "tags": [ "Device" ], "summary": "Exports the list of devices to a CSV file based on the provided filters.\nIf no devices are found, returns a 204 No Content response.", "parameters": [ { "name": "groupMemberIds", "in": "query", "description": "Gets or sets the list of active group member IDs for filtering.\nWhen set, filters devices to include only those owned by users in this group.\nUsed in conjunction with group-based permissions to show devices accessible to group members.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "type", "in": "query", "description": "Gets or sets the device type filter to distinguish between IoT devices and smartphones.", "schema": { "type": "string", "example": "\"iot\", \"iot32\", \"smartphone\"." }, "example": "\"iot\", \"iot32\", \"smartphone\"." }, { "name": "paired", "in": "query", "description": "Gets or sets the pairing status filter to show only paired or unpaired devices.", "schema": { "type": "boolean" } }, { "name": "owner", "in": "query", "description": "Gets or sets the specific owner ID to filter devices by a single user.\nWhen set, returns devices owned by this user or where this user is a collaborator.", "schema": { "type": "string", "example": "\"user123\", \"auth0|123456789\"." }, "example": "\"user123\", \"auth0|123456789\"." }, { "name": "owners", "in": "query", "description": "Gets or sets the list of user IDs to filter devices where users are owners or collaborators.\nSupports complex permission scenarios by allowing multiple user IDs in a single filter.\nWhen combined with GroupMemberIds, uses OR logic to include devices accessible through either mechanism.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filterdUserIds", "in": "query", "description": "Gets or sets the list of user IDs that match a search query.\nThis property is populated by the controller after processing search terms\nand contains user IDs whose profiles match the search criteria.\nUsed internally to filter devices by searchable user information.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "connectionStatus", "in": "query", "description": "Gets or sets the connection status filter to show devices based on their online/offline state.\nDevices are considered online if they have connected within the last 10 minutes.", "schema": { "type": "string", "example": "\"online\", \"offline\"." }, "example": "\"online\", \"offline\"." }, { "name": "state", "in": "query", "description": "Gets or sets the device state filter.", "schema": { "type": "integer", "format": "int32" } }, { "name": "search", "in": "query", "description": "Gets or sets the generic search filter value.", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "description": "Gets or sets the list of ids.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Returns the CSV file." }, "204": { "description": "No devices found to export." } } } }, "/device/{deviceId}": { "get": { "tags": [ "Device" ], "summary": "Retrieves a device by its device identifier.\nChecks user permissions and group access before returning the device details.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the device details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponseDto" } } } }, "403": { "description": "Access denied to the device." }, "404": { "description": "Device not found." } } } }, "/device/{deviceId}/params": { "get": { "tags": [ "Device" ], "summary": "Retrieves the parameters of a device by its device identifier.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the device parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceParams" } } } }, "404": { "description": "Device not found." } } } }, "/device/mqtt_connections": { "get": { "tags": [ "Device" ], "summary": "Retrieves the MQTT connection metrics based on the provided filters.\nDate must be in format YYYY-MM-DD.\n- No parameters: returns all metrics for all devices the user can access.\n- Only SerialNumber: returns all history for that device.\n- Only DeviceId: returns all history for that device.\n- Only Date: returns all devices that connected on that day.\n- SerialNumber + Date: returns the single record.\n- DeviceId + Date: returns the single record.\nUser can only see metrics for devices they have access to (admin, owner, collaborator, or group member).", "parameters": [ { "name": "date", "in": "query", "description": "Gets or sets the date.", "schema": { "type": "string", "format": "date" } }, { "name": "serialNumber", "in": "query", "description": "Gets or sets the serial number.", "schema": { "type": "string" } }, { "name": "deviceId", "in": "query", "description": "Gets or sets the device id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceMqttConnectionsResponseDto" } } } } } } } }, "/device/{deviceId}/iot/files": { "get": { "tags": [ "Device" ], "summary": "Retrieves the list of IoT files for a device from S3 storage.\nFilters files to include only completed .LOG files.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the list of IoT files.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceFileResponseDto" } } } } }, "404": { "description": "Device not found." } } } }, "/device/{deviceId}/iot/files/{fileName}": { "get": { "tags": [ "Device" ], "summary": "Downloads an IoT file for a device from S3 storage.\nConstructs the S3 path based on the file name and device identifier.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } }, { "name": "fileName", "in": "path", "description": "The name of the file to download.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the file." }, "404": { "description": "Device or file not found." }, "500": { "description": "Error downloading the file from S3." } } } }, "/device/{deviceId}/monitor": { "get": { "tags": [ "Device" ], "summary": "Retrieves the monitor data for a device using the MQTT protocol.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the device monitor data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MqttApiMonitorDataDto" } } } }, "400": { "description": "Invalid MQTT response." }, "404": { "description": "Device not found." }, "503": { "description": "Device did not answer in time (offline/unreachable), retry later." } } } }, "/device/{deviceId}/program": { "get": { "tags": [ "Device" ], "summary": "Retrieves the program data for a device using the MQTT protocol.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the device program data." }, "400": { "description": "Invalid MQTT response." }, "404": { "description": "Device not found." }, "503": { "description": "Device did not answer in time (offline/unreachable), retry later." } } } }, "/device/{deviceId}/alarm": { "get": { "tags": [ "Device" ], "summary": "Retrieves the alarm for a device using the MQTT protocol.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the device alarm data.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MqttAlarmDto" } } } } }, "400": { "description": "Invalid MQTT response." }, "404": { "description": "Device not found." }, "503": { "description": "Device did not answer in time (offline/unreachable), retry later." } } } }, "/device/{deviceId}/warning": { "get": { "tags": [ "Device" ], "summary": "Retrieves the warning for a device using the MQTT protocol.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the device warning data.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MqttWarningDto" } } } } }, "400": { "description": "Invalid MQTT response." }, "404": { "description": "Device not found." }, "503": { "description": "Device did not answer in time (offline/unreachable), retry later." } } } }, "/device/{deviceId}/motor-hours-frequency": { "get": { "tags": [ "Device" ], "summary": "Retrieves the motor hours frequency data for a device using the MQTT protocol.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the motor hours frequency data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MqttMotorApiResponseDto" } } } }, "400": { "description": "Invalid MQTT response." }, "404": { "description": "Device not found." }, "503": { "description": "Device did not answer in time (offline/unreachable), retry later." } } } }, "/device/{deviceId}/notes": { "get": { "tags": [ "Device" ], "summary": "Retrieves all notes associated with a device.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the list of device notes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceNoteDto" } } } } }, "404": { "description": "Device not found." } } } }, "/device/{deviceId}/notes/{noteId}/attachments/{attachmentId}": { "get": { "tags": [ "Device" ], "summary": "Downloads an attachment of a device note.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The device identifier.", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "description": "The note identifier.", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "description": "The attachment identifier.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/files/backup/{deviceId}/{fileName}": { "get": { "tags": [ "File" ], "summary": "Downloads a backup file for a specific device.", "parameters": [ { "name": "deviceId", "in": "path", "description": "The unique identifier of the device that owns the backup file.", "required": true, "schema": { "type": "string" } }, { "name": "fileName", "in": "path", "description": "The name of the backup file to download.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the backup file successfully." }, "401": { "description": "Unauthorized - User is not authenticated." }, "403": { "description": "Forbidden - User does not own the device or backup is not completed." }, "404": { "description": "Not Found - Device, backup, or file does not exist." } } } }, "/group": { "get": { "tags": [ "Group" ], "summary": "Retrieves the group associated with the current authenticated user.\nIf the user is the owner of a group, returns the group details with owner information.\nIf the user is a member of a group, returns the group details with member information.\nIf the user has no group and no active invites, returns a 204 No Content response.", "responses": { "200": { "description": "Returns the group details for the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponseDto" } } } }, "204": { "description": "No group or active invite found for the user." }, "500": { "description": "Internal server error if unable to retrieve user or group owner information." } } } }, "/group/{groupId}/users": { "get": { "tags": [ "Group" ], "summary": "Retrieves all users associated with the specified group.\nFor group owners, returns detailed information for all group users including pending invites.\nFor group members, returns information only for active members.", "parameters": [ { "name": "groupId", "in": "path", "description": "The unique identifier of the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the list of group users.", "content": { "application/json": { "schema": { "type": "array", "items": { } } } } }, "404": { "description": "The specified group does not exist." }, "500": { "description": "Internal server error if unable to retrieve user information." } } } }, "/user/countries": { "get": { "tags": [ "User" ], "summary": "Asynchronously retrieves the list of all known countries in the standard (tmcp) format.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryResponse" } } } } } } } }, "/user/whoami": { "get": { "tags": [ "User" ], "summary": "Retrieves the current authenticated user's information.", "responses": { "200": { "description": "Returns the user data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "500": { "description": "Internal server error if unable to retrieve user information." } } } }, "/warnings": { "get": { "tags": [ "Warnings" ], "summary": "Retrieves warning data from the warnings service.\nThis endpoint calls the warnings service to get current warning information.\nNo authentication is required for this endpoint.", "responses": { "200": { "description": "Returns the warning data successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarningsApiResponseDto" } } } } } } }, "/warnings/keys": { "get": { "tags": [ "Warnings" ], "summary": "Retrieves the list of warning keys configuration.", "responses": { "200": { "description": "Returns the list of warning keys.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarningKeyDto" } } } } } } } } }, "components": { "schemas": { "AlarmApiDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Gets or sets the title of the alarm.", "nullable": true }, "code_key": { "type": "string", "description": "Gets or sets the code key of the alarm.", "nullable": true }, "body": { "type": "string", "description": "Gets or sets the body of the alarm.", "nullable": true }, "linkTitle": { "type": "string", "description": "Gets or sets the link title of the alarm.", "nullable": true }, "linkUrl": { "type": "string", "description": "Gets or sets the link url of the alarm.", "nullable": true }, "sectionList": { "type": "string", "description": "Gets or sets the section list of the alarm.", "nullable": true }, "solutions": { "type": "string", "description": "Gets or sets the solutions of the alarm.", "nullable": true } }, "additionalProperties": false, "description": "Represents the alarm data coming from the API." }, "AlarmKeyDto": { "type": "object", "properties": { "key": { "type": "integer", "description": "Gets or sets the key of the alarm.", "format": "int32" }, "code": { "type": "string", "description": "Gets or sets the code of the alarm.", "nullable": true } }, "additionalProperties": false, "description": "Represents the response alarm key object." }, "AlarmsApiResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/AlarmApiDto" }, "description": "Gets or sets the alarms.", "nullable": true } }, "additionalProperties": false, "description": "Represents the response coming from the API." }, "AlarmsConfiguration": { "type": "object", "properties": { "enableEmailNotifications": { "type": "boolean", "description": "Gets or sets a value indicating whether the email notification is enabled." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailNotification" }, "description": "Gets or sets the emails of the notification.", "nullable": true } }, "additionalProperties": false, "description": "Gets or sets the alarms configuration." }, "CoordinateLocation": { "type": "object", "properties": { "latitude": { "type": "number", "description": "Gets or sets the latitude.", "format": "double" }, "longitude": { "type": "number", "description": "Gets or sets the longitude.", "format": "double" } }, "additionalProperties": false, "description": "Represents the location expressed in latitude and longitude." }, "CountryResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Gets or sets the ISO 3166-1 alpha-2 country code (e.g. `IT`).", "nullable": true }, "name": { "type": "string", "description": "Gets or sets the country display name (e.g. `Italy`).", "nullable": true }, "timezones": { "type": "array", "items": { "$ref": "#/components/schemas/Timezone" }, "description": "Gets or sets the time zones associated with the country. A country may span several\ntime zones (e.g. the United States).", "nullable": true } }, "additionalProperties": false, "description": "Represents a country expressed as an ISO 3166-1 alpha-2 code together with its display name and\nthe time zones with which a user's data will be stored." }, "DeviceCollaboratorDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Gets or sets the collaborator email.", "nullable": true }, "readonly": { "type": "boolean", "description": "Gets or sets a value indicating whether the collaborator is readonly or not." } }, "additionalProperties": false, "description": "Represents a payload for the collaborator." }, "DeviceFileResponseDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Gets or sets the name of the file.", "nullable": true }, "size": { "type": "integer", "description": "Gets or sets the size of the file.", "format": "int64" }, "date": { "type": "string", "description": "Gets or sets the date of the file.", "format": "date-time" }, "status": { "type": "string", "description": "Gets or sets the status of the file.", "nullable": true } }, "additionalProperties": false, "description": "Represents the device file response DTO." }, "DeviceMqttConnectionsResponseDto": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Gets or sets deviceId value.", "nullable": true }, "date": { "type": "string", "description": "Gets or sets the date of the metric.", "nullable": true }, "lastConnectionAt": { "type": "string", "description": "Gets or sets the last connection date.", "format": "date-time", "nullable": true }, "connectionsCount": { "type": "integer", "description": "Gets or sets the connected status.", "format": "int32" }, "serialNumber": { "type": "string", "description": "Gets or sets the serial number.", "nullable": true } }, "additionalProperties": false, "description": "Represents the body of the alarms message." }, "DeviceNoteAttachmentDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Gets or sets the unique identifier of the attachment.", "nullable": true }, "fileName": { "type": "string", "description": "Gets or sets the original file name.", "nullable": true }, "size": { "type": "integer", "description": "Gets or sets the file size in bytes.", "format": "int64" }, "contentType": { "type": "string", "description": "Gets or sets the file content type.", "nullable": true }, "uploadedAt": { "type": "string", "description": "Gets or sets the upload date.", "format": "date-time" }, "uploaderId": { "type": "string", "description": "Gets or sets the uploader user id.", "nullable": true }, "uploaderName": { "type": "string", "description": "Gets or sets the uploader name (for display purposes).", "nullable": true } }, "additionalProperties": false, "description": "Data transfer object for device note attachments." }, "DeviceNoteDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Gets or sets the unique identifier of the note.", "nullable": true }, "content": { "type": "string", "description": "Gets or sets the note content as plain text.", "nullable": true }, "contentHtml": { "type": "string", "description": "Gets or sets the sanitized HTML content of the note.\nNull for legacy plain-text notes.", "nullable": true }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceNoteAttachmentDto" }, "description": "Gets or sets the note attachments.", "nullable": true }, "authorId": { "type": "string", "description": "Gets or sets the author id.", "nullable": true }, "authorName": { "type": "string", "description": "Gets or sets the author name.", "nullable": true }, "createdAt": { "type": "string", "description": "Gets or sets the creation date.", "format": "date-time" }, "lastModifiedAt": { "type": "string", "description": "Gets or sets the last modification date.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Data transfer object for device notes." }, "DeviceParams": { "type": "object", "properties": { "btleConnected": { "type": "boolean", "description": "Gets or sets a value indicating whether is connecting through btle.", "nullable": true }, "stateChangedTime": { "type": "integer", "description": "Gets or sets the state changed time.", "format": "int32", "nullable": true }, "numberOfReconnections": { "type": "integer", "description": "Gets or sets the number of re-connections.", "format": "int32", "nullable": true }, "appVersion": { "type": "string", "description": "Gets or sets the app version.", "nullable": true }, "osType": { "type": "string", "description": "Gets or sets the os type.", "nullable": true }, "osVersion": { "type": "string", "description": "Gets or sets the os version.", "nullable": true }, "batteryLevel": { "type": "string", "description": "Gets or sets the battery level.", "nullable": true }, "model": { "type": "string", "description": "Gets or sets the model.", "nullable": true }, "modelIot": { "type": "string", "description": "Gets or sets the model IOT.", "nullable": true }, "modelOpt1": { "type": "string", "description": "Gets or sets the model Opt1.", "nullable": true }, "verFwCtrl": { "type": "string", "description": "Gets or sets the version firmware control.", "nullable": true }, "verFwInv": { "type": "string", "description": "Gets or sets the version firmware inverter.", "nullable": true }, "verFwIot": { "type": "string", "description": "Gets or sets the version firmware IOT.", "nullable": true }, "verFwOpt1": { "type": "string", "description": "Gets or sets the version firmware Opt1.", "nullable": true }, "verHwCtr": { "type": "string", "description": "Gets or sets the version hardware control.", "nullable": true }, "verHwInv": { "type": "string", "description": "Gets or sets the version hardware inverter.", "nullable": true }, "verHwIot": { "type": "string", "description": "Gets or sets the version hardware IOT.", "nullable": true }, "verHwOpt1": { "type": "string", "description": "Gets or sets the version hardware Opt1.", "nullable": true }, "verBlCtr": { "type": "string", "description": "Gets or sets the version Bl control.", "nullable": true }, "verBlInv": { "type": "string", "description": "Gets or sets the version Bl inverter.", "nullable": true }, "verBlIot": { "type": "string", "description": "Gets or sets the version Bl IOT.", "nullable": true }, "verBlOpt1": { "type": "string", "description": "Gets or sets the Bl Opt1.", "nullable": true }, "status": { "$ref": "#/components/schemas/DeviceStatuses" }, "serialNumber": { "type": "string", "description": "Gets or sets the serial number.", "nullable": true } }, "additionalProperties": false, "description": "Represents the device params." }, "DeviceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Gets or sets the Mongo objectId.", "nullable": true }, "createdAt": { "type": "string", "description": "Gets or sets the date and time of the entity creation.", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Gets or sets the date and time of the entity last update.", "format": "date-time", "nullable": true }, "createdBy": { "type": "string", "description": "Gets or sets the who created the entity.", "nullable": true }, "updatedBy": { "type": "string", "description": "Gets or sets who has made the last update to the entity.", "nullable": true }, "name": { "type": "string", "description": "Gets or sets the device name.", "nullable": true }, "deviceId": { "type": "string", "description": "Gets or sets the device identifier.", "nullable": true }, "location": { "type": "string", "description": "Gets or sets the location.", "nullable": true }, "tag": { "type": "string", "description": "Gets or sets the tag.", "nullable": true }, "notes": { "type": "string", "description": "Gets or sets the notes.", "nullable": true }, "lastNoteId": { "type": "string", "description": "Gets or sets the identifier of the most recent note.", "nullable": true }, "gpsCoordinates": { "$ref": "#/components/schemas/CoordinateLocation" }, "firstConnection": { "type": "string", "description": "Gets or sets the first connection date.", "format": "date-time", "nullable": true }, "lastConnection": { "type": "string", "description": "Gets or sets the last connection date.", "format": "date-time", "nullable": true }, "locationChangedByUser": { "type": "boolean", "description": "Gets or sets a value indicating whether the location has change by the user." }, "gpsCoordinatesChangedByUser": { "type": "boolean", "description": "Gets or sets a value indicating whether the GPS coordinates have been changed by the user." }, "owner": { "$ref": "#/components/schemas/UserResponse" }, "collaborators": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceCollaboratorDto" }, "description": "Gets or sets the device collaborators.", "nullable": true }, "currentInverter": { "type": "string", "description": "Gets or sets the current inverter.", "nullable": true }, "alarmsConfiguration": { "$ref": "#/components/schemas/AlarmsConfiguration" }, "createTodoAutomatically": { "type": "boolean", "description": "Gets or sets a value indicating whether the alarms and warnings chosen in\nTM.Nastec.Remo.Core.Application.Dtos.Devices.DeviceResponseDto.TodoConfiguration raise a ToDo on this device." }, "todoConfiguration": { "$ref": "#/components/schemas/TodoConfiguration" }, "warningsConfiguration": { "$ref": "#/components/schemas/WarningsConfiguration" }, "params": { "$ref": "#/components/schemas/DeviceParams" }, "settings": { "$ref": "#/components/schemas/DeviceSettings" }, "deviceType": { "$ref": "#/components/schemas/DeviceType" }, "iot": { "type": "boolean", "description": "Gets a value indicating whether the device is any IOT variant (Iot or Iot32).\nMaintained for backward compatibility.", "readOnly": true }, "isIot32": { "type": "boolean", "description": "Gets a value indicating whether the device is IOT ESP32.", "readOnly": true }, "addressIsInvalid": { "type": "boolean", "description": "Gets or sets a value indicating whether the device address needs recalculation." }, "geocodingRetryCount": { "type": "integer", "description": "Gets or sets the number of consecutive failed geocoding attempts.", "format": "int32" }, "userPermission": { "$ref": "#/components/schemas/GroupUserPermission" } }, "additionalProperties": false, "description": "Represents the device response dto." }, "DeviceSettings": { "type": "object", "properties": { "refreshInterval": { "type": "integer", "description": "Gets or sets the refresh interval.", "format": "int32", "nullable": true } }, "additionalProperties": false, "description": "Gets or sets the device settings." }, "DeviceStatuses": { "enum": [ 0, 1, 2, 3, 4, 5, -1 ], "type": "integer", "description": "Represents the possible statuses of a Device.", "format": "int32" }, "DeviceType": { "enum": [ 0, 1, 2 ], "type": "integer", "description": "Represents the type of a Device.", "format": "int32" }, "EmailNotification": { "type": "object", "properties": { "address": { "type": "string", "description": "Gets or sets the address.", "nullable": true }, "key": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the key of the notification.", "nullable": true } }, "additionalProperties": false, "description": "Represents the email notification." }, "GroupResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Gets or sets the Id.", "nullable": true }, "name": { "type": "string", "description": "Gets or sets the Name.", "nullable": true }, "description": { "type": "string", "description": "Gets or sets the Description.", "nullable": true }, "notes": { "type": "string", "description": "Gets or sets the Notes.", "nullable": true }, "owner": { "$ref": "#/components/schemas/UserResponse" } }, "additionalProperties": false, "description": "Represents the group response dto." }, "GroupUserPermission": { "enum": [ 0, 1, 2 ], "type": "integer", "description": "Represents the possible permissions of a GroupUser.", "format": "int32" }, "MqttAlarmDto": { "type": "object", "properties": { "key": { "type": "integer", "description": "Gets or sets the key of the alarm.", "format": "int32" }, "alarmName": { "type": "string", "description": "Gets or sets the alarm name.", "nullable": true }, "upTime": { "type": "string", "description": "Gets or sets the alarm uptime (expressed in seconds).", "nullable": true } }, "additionalProperties": false, "description": "Represents the alarm of the drive." }, "MqttApiMonitorDataDto": { "type": "object", "properties": { "alarms": { "type": "array", "items": { "$ref": "#/components/schemas/MqttAlarmDto" }, "description": "Gets or sets the alarms of the drive.", "nullable": true }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/MqttWarningDto" }, "description": "Gets or sets the warnings of the drive.", "nullable": true }, "params": { "type": "array", "items": { "$ref": "#/components/schemas/MqttParamDto" }, "description": "Gets or sets the params of the drive.", "nullable": true }, "status": { "$ref": "#/components/schemas/MqttStatusDto" } }, "additionalProperties": false, "description": "Represents the monitor data." }, "MqttMotorApiResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MqttMotorFrequencyDto" }, "description": "Gets or sets the data of the motor request.", "nullable": true } }, "additionalProperties": false, "description": "Represents the response for motor api request." }, "MqttMotorFrequencyDto": { "type": "object", "properties": { "frequency": { "type": "string", "description": "Gets or sets the frequency of the motor.", "nullable": true }, "hours": { "type": "integer", "description": "Gets or sets the hours of the motor.", "format": "int32" } }, "additionalProperties": false, "description": "Gets or sets the motor frequency data." }, "MqttParamDto": { "type": "object", "properties": { "key": { "type": "string", "description": "Gets or sets the key of the param.", "nullable": true }, "name": { "type": "string", "description": "Gets or sets the name of the param.", "nullable": true }, "data": { "type": "string", "description": "Gets or sets the data of the param.", "nullable": true }, "unit": { "type": "string", "description": "Gets or sets the unit of the param.", "nullable": true } }, "additionalProperties": false, "description": "Represents the param of the drive." }, "MqttStatusDto": { "type": "object", "properties": { "code": { "type": "integer", "description": "Gets or sets the code of the status.", "format": "int32" }, "text": { "type": "string", "description": "Gets or sets the text of the status.", "nullable": true } }, "additionalProperties": false, "description": "Represents the status of the drive." }, "MqttWarningDto": { "type": "object", "properties": { "key": { "type": "integer", "description": "Gets or sets the key of the warning.", "format": "int32" }, "warningName": { "type": "string", "description": "Gets or sets the warning name.", "nullable": true }, "upTime": { "type": "string", "description": "Gets or sets the warning uptime (expressed in seconds).", "nullable": true } }, "additionalProperties": false, "description": "Represents the warning of the drive." }, "Timezone": { "type": "object", "properties": { "id": { "type": "string", "description": "Gets or sets the IANA time zone identifier (e.g. `Europe/Rome`).", "nullable": true }, "offset": { "type": "string", "description": "Gets or sets the current UTC offset of the time zone (e.g. `+01:00`).", "nullable": true } }, "additionalProperties": false, "description": "Represents a time zone associated with a country, expressed as an IANA identifier together with\nits current UTC offset." }, "TodoConfiguration": { "type": "object", "properties": { "alarmKeys": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the keys of the alarms that raise a ToDo. Same format of the\nemail ones: \"all\", or the single keys. Empty means no ToDo at all.", "nullable": true }, "warningKeys": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the keys of the warnings that raise a ToDo.", "nullable": true } }, "additionalProperties": false, "description": "The alarms and warnings of a device that raise a ToDo on their own, whether\nor not they also notify somebody by email." }, "UserLocation": { "type": "object", "properties": { "address": { "type": "string", "description": "Gets or sets the address of the location.", "nullable": true }, "city": { "type": "string", "description": "Gets or sets the city of the location.", "nullable": true }, "province": { "type": "string", "description": "Gets or sets the province of the location.", "nullable": true }, "country": { "type": "string", "description": "Gets or sets the country of the location.", "nullable": true } }, "additionalProperties": false, "description": "Represents the location of the user." }, "UserPolicies": { "type": "object", "properties": { "settings": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Settings section." }, "monitor": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Monitor section." }, "program": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Program section." }, "alarms": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Alarms section." }, "warnings": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Warnings section." }, "charts": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Charts section." }, "camera": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the Camera section." }, "apiKeys": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has access to the API Keys section." } }, "additionalProperties": false, "description": "Represents the user policies for accessing different sections of the application." }, "UserResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Gets or sets the Mongo objectId.", "nullable": true }, "createdAt": { "type": "string", "description": "Gets or sets the date and time of the entity creation.", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Gets or sets the date and time of the entity last update.", "format": "date-time", "nullable": true }, "createdBy": { "type": "string", "description": "Gets or sets the who created the entity.", "nullable": true }, "updatedBy": { "type": "string", "description": "Gets or sets who has made the last update to the entity.", "nullable": true }, "firstName": { "type": "string", "description": "Gets or sets the first name of the user.", "nullable": true }, "lastName": { "type": "string", "description": "Gets or sets the last name of the user.", "nullable": true }, "email": { "type": "string", "description": "Gets or sets the email address of the user.", "nullable": true }, "lastAccess": { "type": "string", "description": "Gets or sets the last login date and time.", "format": "date-time", "nullable": true }, "phoneNumber": { "type": "string", "description": "Gets or sets the phone number.", "nullable": true }, "active": { "type": "boolean", "description": "Gets or sets a value indicating whether the user is active." }, "confirmed": { "type": "boolean", "description": "Gets or sets a value indicating whether the user is confirmed." }, "master": { "type": "boolean", "description": "Gets or sets a value indicating whether the user is a master." }, "location": { "$ref": "#/components/schemas/UserLocation" }, "company": { "type": "string", "description": "Gets or sets the user company.", "nullable": true }, "preferredLanguage": { "type": "string", "description": "Gets or sets the user's preferred language code (e.g. \"en_uk\", \"it\"); null means English.", "nullable": true }, "country": { "type": "string", "description": "Gets or sets the country of the user as an ISO 3166-1 alpha-2 code (e.g. `IT`).", "nullable": true }, "timezone": { "type": "string", "description": "Gets or sets the time zone of the user as an IANA time zone identifier (e.g. `Europe/Rome`).", "nullable": true }, "userId": { "type": "integer", "description": "Gets or sets the user id.", "format": "int32" }, "isServiceSuperUser": { "type": "boolean", "description": "Gets or sets a value indicating whether the user is service super-user." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Gets or sets the user roles.", "nullable": true }, "bootloader": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has bootloader access." }, "remo": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has remo access." }, "service": { "type": "boolean", "description": "Gets or sets a value indicating whether the user has service access." }, "code": { "type": "string", "description": "Gets or sets the code of the user.", "nullable": true }, "registeredFrom": { "type": "string", "description": "Gets or sets the service from which the user has logged in.", "nullable": true }, "unyconnectLoginAt": { "type": "string", "description": "Gets or sets the last login at Unyconnect service.", "format": "date-time", "nullable": true }, "nastecnowLoginAt": { "type": "string", "description": "Gets or sets the last login at NastecNow service.", "format": "date-time", "nullable": true }, "policies": { "$ref": "#/components/schemas/UserPolicies" } }, "additionalProperties": false, "description": "Represents the user dto." }, "WarningApiDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Gets or sets the title of the warning.", "nullable": true }, "code_key": { "type": "string", "description": "Gets or sets the code key of the warning.", "nullable": true }, "body": { "type": "string", "description": "Gets or sets the body of the warning.", "nullable": true }, "linkTitle": { "type": "string", "description": "Gets or sets the link title of the warning.", "nullable": true }, "linkUrl": { "type": "string", "description": "Gets or sets the link url of the warning.", "nullable": true }, "sectionList": { "type": "string", "description": "Gets or sets the section list of the warning.", "nullable": true }, "solutions": { "type": "string", "description": "Gets or sets the solutions of the warning.", "nullable": true } }, "additionalProperties": false, "description": "Represents the warning data coming from the API (identico a AlarmApiDto)." }, "WarningKeyDto": { "type": "object", "properties": { "key": { "type": "integer", "description": "Gets or sets the warning key.", "format": "int32" }, "code": { "type": "string", "description": "Gets or sets the warning code.", "nullable": true } }, "additionalProperties": false, "description": "Represents the warning key data coming from the API." }, "WarningsApiResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WarningApiDto" }, "description": "Gets or sets the warnings.", "nullable": true } }, "additionalProperties": false, "description": "Represents the response coming from the API." }, "WarningsConfiguration": { "type": "object", "properties": { "enableEmailNotifications": { "type": "boolean", "description": "Gets or sets a value indicating whether the email notification is enabled." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailNotification" }, "description": "Gets or sets the emails of the notification.", "nullable": true } }, "additionalProperties": false, "description": "Gets or sets the warnings configuration." } }, "securitySchemes": { "api_key": { "type": "apiKey", "description": "API Key authentication. Provide your API key in the X-Api-Key header.", "name": "X-Api-Key", "in": "header" } } }, "security": [ { "api_key": [ ] } ], "tags": [ { "name": "Alarms", "description": "Handles alarm-related operations." }, { "name": "Device", "description": "Handles device-related operations." }, { "name": "File", "description": "Handles file-related operation." }, { "name": "Group", "description": "Handles group-related operations." }, { "name": "User", "description": "Handles user-related operations." }, { "name": "Warnings", "description": "Handles warning-related operations." } ] }