openapi: 3.0.0
info:
  description: IE Runtime Public API documentation.
  title: IE Runtime Public APIs
  version: "2.1"
  contact:
    name: Team ADI
  license:
    name: Industrial Edge © 2025, Siemens AG. All rights reserved.
servers:
  - url: https://{edgeDeviceHost}/device/edge/api/v2
    description: Public URL - Hostname or IP address of the Edge Device
    variables:
      edgeDeviceHost:
        default: edge-device-hostname
        description: The hostname or IP address of the Edge Device.
  - url: https://edge-iot-core.proxy-redirect/device/edge/api/v2
    description: Application Container URL - This can be used from application container only
tags:
  - name: device
  - name: login
  - name: notifications
  - name: check
  - name: networks
paths:
  /activate:
    post:
      description: |-
        - This method can be used to activate an IE Runtime and registers the same on the IE Management.

        - To activate the runtime using this method, an activation json file is required in the request payload

        **Note:**
        - The activation json file can be obtained via the IEM App Portal API endpoint - /devices/create
      tags:
        - device
      summary: Activate IE Runtime
      operationId: post-activate
      responses:
        "204":
          description: Successful operation
        "400":
          description: |-
            Bad Request:
            - On-boarding file required
            - Invalid file name
            - Invalid activation file
            - Failed to parse body map
            - Invalid docker IP wrong netmask
            - Invalid docker IP wrong A address
            - Invalid docker IP wrong B1 address
            - Invalid docker IP wrong B2 address
            - Invalid docker IP wrong B3 address
            - Invalid docker IP wrong host
            - Invalid docker IP
            - Docker zero IP conflicts with an existing subnet of the device.
            - Domain length exceeds 255
            - Domain label cannot begin with a period
            - Domain label length exceeds 63
            - Domain label begins with a hyphen
            - Domain label ends with a hyphen
            - Invalid rune at offset in domain
            - Invalid character in domain
            - Domain cannot end with a period
            - Domain length exceed 63
            - Top level domain begins with a hyphen
            - Top level domain ends with a hyphen
            - Top level domain begins with a digit
            - Invalid IP address
            - Invalid netmask
            - Invalid IP range
            - IP range invalid last digit
            - Invalid gateway
            - Invalid aux addresses
            - Zero usable IP Addresses
            - Device name unavailable
            - Invalid certificate
            - Unable to parse on-boarding file
            - Invalid MAC address
            - Wrong MAC address
            - Failed to apply network settings, due to invalid IP
            - Wrong gateway address
            - Wrong netmask address
            - Wrong DNS address
            - Invalid certificate details (**Note:** For this error, the error message depends on the specific error)
            - Unable to connect proxy server, please check network settings or proxy configuration
            - Enter valid proxy credentials for authentication
            - Invalid APN format. Enter 1-100 characters using lowercase letters, digits and hyphens. Hyphens cannot be at the start or end.
            - Invalid username. Enter up to 64 characters using letters, digits, periods, underscores or hyphens.
            - Invalid password. Enter up to 64 characters using letters, digits, periods, underscores or hyphens.
            - Invalid PIN. Enter 4-8 digits only.
            - Remove the MAC address and static IP settings. These are not supported for cellular connections.
            - Invalid network configuration. (**Note:** For this error, the error message depends on the specific error)
            - The device does not have cellular capabilities. Please check the device specifications and ensure that it supports cellular connectivity.
            - APN is required.
            - The device configuration file no longer exists on the IEM.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleOnboardingFileRequiredError:
                  value:
                    errors:
                      - code: edge.onboardingfileRequired
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Onboarding file is required.
                ExampleInvalidFileNameError:
                  value:
                    errors:
                      - code: edge.invalidFileName
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid filename.
                ExampleInvalidActivationFile:
                  value:
                    errors:
                      - code: edge.invalidActivationFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid Edge Device onboarding file, please provide valid details.
                ExampleFailedToParseBodyMapError:
                  value:
                    errors:
                      - code: edge.failedToParseBodyMap
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to parse entity.
                ExampleInvalidDockerIPWrongNetmaskError:
                  value:
                    errors:
                      - code: edge.invalidDockerIpWrongNM
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP netmask should only be 255.255.0.0 (or CIDR value must be 16)
                ExampleInvalidDockerIPWrongAddressAError:
                  value:
                    errors:
                      - code: edge.invalidDockerIpWrongAddressA
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP should start with 172, 192 or 10
                ExampleInvalidDockerIPWrongAddressB1Error:
                  value:
                    errors:
                      - code: edge.invalidDockerIpWrongAddressB1
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP b address should be between 16 to 31 (for 172 family)
                ExampleInvalidDockerIPWrongAddressB2Error:
                  value:
                    errors:
                      - code: edge.invalidDockerIpWrongAddressB2
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP b address should be between 0 to 255 (for 10 family)
                ExampleInvalidDockerIPWrongAddressB3Error:
                  value:
                    errors:
                      - code: edge.invalidDockerIpWrongAddressB3
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP for 172 family should only be 172.168.0.0
                ExampleInvalidDockerIPWrongHostError:
                  value:
                    errors:
                      - code: edge.invalidDockerIpWrongHost
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP should be in the format - x.y.0.0
                ExampleInvalidDockerIPError:
                  value:
                    errors:
                      - code: edge.invalidDockerIp
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker IP is invalid.
                ExampleDomainLengthExceeds255Error:
                  value:
                    errors:
                      - code: edge.ntp.exceedDomainLength255
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: domain name length cannot exceed 255."
                ExampleDomainLabelCannotBeginWithAPeriodError:
                  value:
                    errors:
                      - code: edge.ntp.domainLabelCannotBeginWithAPeriod
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: label cannot begin with a period."
                ExampleDomainLabelLengthExceeds63Error:
                  value:
                    errors:
                      - code: edge.ntp.exceedDomainLabelLength63
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: label byte length cannot exceed 63."
                ExampleDomainLabelBeginsWithAHyphenError:
                  value:
                    errors:
                      - code: edge.ntp.domainLabelBeginsWithAHyphen
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: label begins with a hyphen."
                ExampleDomainLabelEndsWithAHyphenError:
                  value:
                    errors:
                      - code: edge.ntp.domainLabelEndsWithAHyphen
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: label ends with a hyphen."
                ExampleInvalidRuneAtOffsetInDomainError:
                  value:
                    errors:
                      - code: edge.ntp.invalidRuneAtOffsetInDomain
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: invalid rune."
                ExampleInvalidCharacterInDomainError:
                  value:
                    errors:
                      - code: edge.ntp.invalidCharacterInDomain
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: invalid character in domain."
                ExampleDomainCannotEndWithAPeriodError:
                  value:
                    errors:
                      - code: edge.ntp.domainCannotEndWithAPeriod
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: top level domain cannot end with a period."
                ExampleDomainLengthExceed63Error:
                  value:
                    errors:
                      - code: edge.ntp.exceedDomainLength63
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: byte length of top level domain cannot exceed 63."
                ExampleTopLevelDomainBeginsWithAHyphenError:
                  value:
                    errors:
                      - code: "edge.ntp.topLevelDomainBeginsWithAHyphen  "
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: top level domain is beginning with a hyphen."
                ExampleTopLevelDomainEndsWithAHyphenError:
                  value:
                    errors:
                      - code: edge.ntp.topLevelDomainEndsWithAHyphen
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: top level domain is ends with a hyphen."
                ExampleTopLevelDomainBeginsWithADigitError:
                  value:
                    errors:
                      - code: edge.ntp.topLevelDomainBeginsWithADigit
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "NTP server - Invalid domain: top level domain is beginning with a digit."
                ExampleInvalidIPAddressError:
                  value:
                    errors:
                      - code: edge.l2network.invalidIPAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid IP address.
                ExampleInvalidNetMaskError:
                  value:
                    errors:
                      - code: edge.l2network.invalidNetMask
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid netmask.
                ExampleInvalidIPRangeError:
                  value:
                    errors:
                      - code: edge.l2network.invalidIpRange
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid IP range.
                ExampleIPRangeError:
                  value:
                    errors:
                      - code: edge.l2network.invalidIpRangeError
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Last digit of an IP address is odd, then IP range should be 1.
                ExampleInvalidGatewayError:
                  value:
                    errors:
                      - code: edge.l2network.invalidGateway
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid gateway address.
                ExampleInvalidAuxAddressesError:
                  value:
                    errors:
                      - code: edge.l2network.invalidAuxAddresses
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid auxiliary address list.
                ExampleZeroUsableIPAddressesError:
                  value:
                    errors:
                      - code: edge.l2network.zeroUsableIpAddresses
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The selected range returns in 0 usable addresses, please select a different range.
                ExampleInvalidCertificateError:
                  value:
                    errors:
                      - code: edge.InvalidCertificates
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid certificates.
                ExampleUnableToParseOnboardingFileError:
                  value:
                    errors:
                      - code: edge.unableToParseOnboardingFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to parse onboarding file.
                ExampleInvalidMACAddressError:
                  value:
                    errors:
                      - code: edge.invalidMACAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid MAC address in onboarding file, please change and retry.
                ExampleWrongMACAddressError:
                  value:
                    errors:
                      - code: edge.wrongMacAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply network settings, wrong MAC address.
                ExampleDeviceIPAddressError:
                  value:
                    errors:
                      - code: edge.deviceipAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Failed to apply network settings, invalid IP address."
                ExampleWrongGatewayAddressError:
                  value:
                    errors:
                      - code: edge.wrongGatewayAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply network settings, invalid gateway address.
                ExampleWrongNetmaskAddressError:
                  value:
                    errors:
                      - code: edge.wrongNetmaskAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply network settings, invalid netmask address.
                ExampleWrongDNSAddressError:
                  value:
                    errors:
                      - code: edge.wrongDNSAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply network settings, invalid DNS address.
                ExampleInvalidCertificateDetailsError:
                  value:
                    errors:
                      - code: edge.certificate.InvalidCertificateDetails
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid certificate: %s"
                ExampleDeviceNameUnavailableError:
                  value:
                    errors:
                      - code: edge.nameUnavailable
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Name of Edge Device not available.
                ExampleInvalidProxyConfiguration:
                  value:
                    errors:
                      - code: edge.proxy.checkProxySettings
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to connect proxy server, please check network settings or proxy configuration.
                ExampleInvalidProxyCredentials:
                  value:
                    errors:
                      - code: edge.proxy.proxyAuthRequired
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Enter valid proxy credentials for authentication.
                ExampleNotFoundDevice:
                  value:
                    errors:
                      - code: notFound.device
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The device configuration file no longer exists on the IEM.
                ExampleDockerZeroIPSubnetConflict:
                  value:
                    errors:
                      - code: edge.dockerZeroIPSubnetConflict
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Docker zero IP conflicts with an existing subnet of the device.
                ExampleInvalidCellularConfiguration:
                  value:
                    errors:
                      - code: edge.invalid.cellular.configuration
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Remove the MAC address and static IP settings. These are not supported for cellular connections."
                ExampleEmptyCellularConfigurationAPN:
                  value:
                    errors:
                      - code: edge.empty.cellular.apn
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "APN is required."
                ExampleInvalidCellularConfigurationAPN:
                  value:
                    errors:
                      - code: edge.invalid.cellular.apn
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid APN format. Enter 1-100 characters using lowercase letters, digits and hyphens. Hyphens cannot be at the start or end."
                ExampleInvalidCellularConfigurationPIN:
                  value:
                    errors:
                      - code: edge.invalid.cellular.pin
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid PIN. Enter 4-8 digits only."
                ExampleInvalidCellularConfigurationUsername:
                  value:
                    errors:
                      - code: edge.invalid.cellular.username
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid username. Enter up to 64 characters using letters, digits, periods, underscores or hyphens."
                ExampleInvalidCellularConfigurationPassword:
                  value:
                    errors:
                      - code: edge.invalid.cellular.password
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid password. Enter up to 64 characters using letters, digits, periods, underscores or hyphens."
                ExampleInvalidConfigurationDueToGatewayInterface:
                  value:
                    errors:
                      - code: edge.gatewayInterfaceNotConfigured
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid network configuration. At least one gateway interface must be configured."
                ExampleInvalidConfigurationMultipleGatewayInterface:
                  value:
                    errors:
                      - code: edge.multipleGatewayInterfacesConfigured
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid network configuration. Only one gateway interface can be configured."
                ExampleCellularNotCapableError:
                  value:
                    errors:
                      - code: edge.cellular.notCapable
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "The device does not have cellular capabilities. Please check the device specifications and ensure that it supports cellular connectivity."

        "401":
          description: |-
            Unauthorized:
            - Token expired
            - Invalid activation file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleTokenExpiredError:
                  value:
                    errors:
                      - code: edge.tokenExpired
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Onboarding file expired - please recreate.
                ExampleInvalidActivationFileError:
                  value:
                    errors:
                      - code: edge.invalidActivationFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid Edge Device onboarding file, please provide valid details.
        "405":
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleNotSupportedError:
                  $ref: "#/components/examples/NotSupported"
        "409":
          description: |-
            Conflict:
            - Activation in-progress
            - Already activated
            - Retry on-board configuration conflict
            - Retry with new on-boarding file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleAlreadyActivatedError:
                  value:
                    errors:
                      - code: edge.alreadyActivated
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Edge Device is already activated.
                ExampleActivationInprogressError:
                  value:
                    errors:
                      - code: edge.activationInprogress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Activation is in progress.
                ExampleRetryOnboardConfigurationConflictError:
                  value:
                    errors:
                      - code: edge.retryOnboardConfigurationConflict
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Retry onboarding. A configuration-related problem has been detected.
                ExampleRetryWithNewOnboardingFileError:
                  value:
                    errors:
                      - code: edge.retryWithNewOnboardingFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Device instance already onboarded. Please create a new onboarding file from the IEM and retry.
        "413":
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleFileSizeExceededError:
                  value:
                    errors:
                      - code: edge.file.size.configExceeded
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: File size exceeds the allowed limit of 2 MB.
        "500":
          description: |-
            Internal Server Error:
            - No space available for upload on-boarding file
            - Unable to upload on-boarding file
            - Failed to parse on-boarding file
            - Time mismatch with IEM
            - Unable to add NTP servers
            - Unable to generate token
            - Unable to add device information in database
            - Check internet settings
            - Applying network settings failed
            - Setting docker IP failed
            - Unable to get IP Address
            - Unable to change container DNS
            - Unable to read capabilities
            - Setting NTP server failed
            - Applying proxy settings failed
            - Applying nginx settings failed
            - Nginx configuration test failed
            - DNS configuration failed
            - Unable to parse data
            - Certificate expired
            - Unable to add certificates
            - Generic internal server error
            - Failed to create the cellular connection. Please review your configuration and try again..
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleNoSpaceAvailableForUploadOnboardingFileError:
                  value:
                    errors:
                      - code: edge.noSpaceAvailableForUploadOnboardingFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Required space is not available on the Edge Device to the upload onboarding file.
                ExampleUnableToUploadOnboardingFile:
                  value:
                    errors:
                      - code: edge.unabletoUploadOnboardingFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to upload onboarding file.
                ExampleFailedToParseOnboardingFile:
                  value:
                    errors:
                      - code: edge.failedToParseOnboardingFile
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to parse onboarding file.
                ExampleInternalServerError:
                  value:
                    errors:
                      - code: edge.internalServerError
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The server encountered an unknown error.
                ExampleUnableToGenerateTokenError:
                  value:
                    errors:
                      - code: edge.unableToGenerateToken
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to generate token.
                ExampleUnableToAddDeviceInfoInDatabaseError:
                  value:
                    errors:
                      - code: edge.UnableToAddDeviceInfoInDB
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to add Edge Device information to the database.
                ExampleCheckInternetSettingsError:
                  value:
                    errors:
                      - code: edge.checkInternetSettings
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to connect to the IEM. Please check internet settings, network configuration and retry.
                ExampleApplyingNWSettingsFailedError:
                  value:
                    errors:
                      - code: edge.applyingNWSettingsFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply network settings.
                ExampleSetDockerIPFailedError:
                  value:
                    errors:
                      - code: edge.setDockerIPFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to set docker0 IP.
                ExampleUnableToGetIPAddressError:
                  value:
                    errors:
                      - code: edge.unableToGetIPAddress
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to get the IP address of the Edge Device.
                ExampleUnableToChangeContainerDnsError:
                  value:
                    errors:
                      - code: edge.unableToChangeContainerDns
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to change container dns.
                ExampleUnableToReadCapabilitiesError:
                  value:
                    errors:
                      - code: edge.unableToReadCapabilities
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to read capabilities configuration file.
                ExampleNTPServerFailedError:
                  value:
                    errors:
                      - code: edge.ntpServerFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to set the NTP server
                ExampleProxySettingFailedError:
                  value:
                    errors:
                      - code: edge.proxySettingFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply prox settings.
                ExampleNGINXSettingFailedError:
                  value:
                    errors:
                      - code: edge.nginxSettingFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to apply nginx settings, hostname could not parse the URL of the IEM.
                ExampleNGINXConfigTestFailedError:
                  value:
                    errors:
                      - code: edge.nginxConfigTestFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Nginx configuration test failed.
                ExampleDNSConfigFailedError:
                  value:
                    errors:
                      - code: edge.dnsConfigFailed
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Check the DNS server configuration. The DNS server must be properly configured and reachable by the IEM.
                ExampleIEDOutOfSyncWithIEMError:
                  value:
                    errors:
                      - code: edge.time.mismatch
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The time on the IED is not synchronized with the IEM. Please adjust NTP settings and retry.
                ExampleUnableToAddNTPServersError:
                  value:
                    errors:
                      - code: edge.ntp.unableToAddNTPServers
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to add NTP servers.
                ExampleUnableToParseError:
                  value:
                    errors:
                      - code: edge.unableToParse
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to parse data.
                ExampleTimeMismatchWithIEMError:
                  value:
                    errors:
                      - code: edge.time.mismatch
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The time on the IED is not synchronized with the IEM. Please adjust NTP settings and retry.
                ExampleCertificateExpiredError:
                  value:
                    errors:
                      - code: edge.certificateExpired
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The certificate has expired or is not yet valid. Synchronize the device time.
                ExampleUnableToAddCertificatesError:
                  value:
                    errors:
                      - code: edge.unableToAddCertificates
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to add trust certificates.
                ExampleUnableToCreateCellularConnectionError:
                  value:
                    errors:
                      - code: edge.unableToCreateCellularConnection
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Failed to create the cellular connection. Please review your configuration and try again.
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleNTPServiceNotRunningError:
                  value:
                    errors:
                      - code: edge.NTPServiceNotRunning
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: NTP service is not running on the host.
      parameters: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: string
                  description: The activation JSON needs to be uploaded against this key
        description: JSON file created from IEM for the purpose of activating your edge runtime
    parameters: []
  /hard-reset:
    post:
      description: |-
        - This method hard resets the edge device (i.e. both runtime & host system)

        - It restores the device to its original pre-onboard state
      tags:
        - device
      summary: Hard-reset IE Device
      operationId: post-hard-reset
      responses:
        "202":
          description: |-
            Accepted:
            - Successfully triggered factory reset. The success of the asynchronous operation is not guaranteed
        "400":
          description: |-
            Bad Request
            - Invalid request body
            - Invalid command
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleInvalidRequestBody:
                  $ref: "#/components/examples/InvalidRequestBody"
                ExampleInvalidCommand:
                  $ref: "#/components/examples/InvalidCommand"
        "401":
          description: |-
            Unauthorized:
            - Expired token
            - Invalid token
            - Missing token
            - Token user not found
            - Unable to verify token
            - Not permitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleExpiredTokenError:
                  $ref: "#/components/examples/ExpiredToken"
                ExampleInvalidTokenError:
                  $ref: "#/components/examples/InvalidToken"
                ExampleTokenUserNotFound:
                  $ref: "#/components/examples/TokenUserNotFound"
                ExampleUnableToVerifyToken:
                  $ref: "#/components/examples/UnableToVerifyToken"
                ExampleMissingToken:
                  $ref: "#/components/examples/MissingToken"
                ExampleNotPermitted:
                  $ref: "#/components/examples/NotPermitted"
        "409":
          description: |-
            Conflict:
            - Conflict with device state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleSystemCommandRunning:
                  $ref: "#/components/examples/SystemCommandRunning"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleInternalServerError:
                  $ref: "#/components/examples/InternalServerError"
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleServiceNotRunning:
                  $ref: "#/components/examples/ServiceNotRunning"
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
      security:
        - API_Key_1: []
  /login/direct:
    post:
      tags:
        - login
      summary: Log in with username and password
      description: |-
        This allows a user to login into the IE Runtime using:
        - Username
        - Password
        - Verification Code (if multi-factor verification is enabled).

        **Note:**
        verificationCode in body will pass when a user is invited for user management.
        edge.login.invalidLoginCredentials code will appears in case of capability ID 'host.authservice' is local-umc.
      operationId: post-login-direct
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
              examples:
                LoginDirectResponse:
                  value:
                    accessToken: 58fc256a-5599-42e0-bbee-9d63030bf1ce
                    refreshToken: 4a213346-0c45-418c-a6ee-b0e56a7f7b37
                    expiresAt: 1683740508
        "400":
          description: |-
            Bad Request:
            - Missing user name
            - Missing password
            - Invalid verification code
            - Unable to approve user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                MissingUserName:
                  value:
                    errors:
                      - code: edge.login.missingUserName
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Username is required.
                "MissingPassword ":
                  value:
                    errors:
                      - code: edge.login.missingPassword
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Password is required.
                MissingVerificationCode:
                  value:
                    errors:
                      - code: edge.login.missingVerificationCode
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Verification code is required.
                InvalidVerificationCode:
                  value:
                    errors:
                      - code: edge.login.invalidVerificationCode
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid verification code.
                UnableToApproveUser:
                  value:
                    errors:
                      - code: edge.login.unableToApproveUser
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to approve user.
        "401":
          description: |-
            Unauthorized:
            - Invalid login credentials with retry counts.
            - Maximum user login attempt exceeded.
            - Invalid login credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InvalidLoginCredentialWithRetries:
                  value:
                    errors:
                      - code: edge.login.invalidLoginCredentialWithRetries
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: "Invalid credentials. Try again. Login retries left:"
                MaxAttemptExceeded:
                  value:
                    errors:
                      - code: edge.login.maxAttemptExceeded
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: You have exceeded the maximum number of login attempts. Please try again in 15 minutes.
                InvalidLoginCredentials:
                  value:
                    errors:
                      - code: edge.login.invalidLoginCredentials
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid credentials, retry.
        "500":
          description: |-
            InternalServerError:
            - Internal Server Error
            - Contact to admin for user approval
            - User already verified
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  value:
                    errors:
                      - code: edge.internalServerError
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The server encountered an unknown error.
                ContactToAdminForApproval:
                  value:
                    errors:
                      - code: edge.login.contactToAdminForApproval
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: User status is pending, contact admin for approval.
                UserAlreadyVerified:
                  value:
                    errors:
                      - code: edge.login.userAlreadyVerified
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: User already verified.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Login"
            examples:
              LoginRequestWithVerificationCode:
                value:
                  username: mock@email.com
                  password: mockPassword
                  verificationCode: H2OrIXOY
              LoginRequest:
                value:
                  username: mock@email.com
                  password: mockPassword
        description: The map of login credentials, including username, password and verificationCode (optional)
  /logout:
    post:
      summary: Logout from IE Runtime
      tags:
        - login
      responses:
        "204":
          description: No Content
        "401":
          $ref: "#/components/responses/TokenError"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleInternalServerError:
                  $ref: "#/components/examples/InternalServerError"
      operationId: post-logout
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
      description: |-
        This method can be used to logout from the IE runtime, it involves the following:

        - Termination of the user session

        - Disassociation of authenticated user role from the client's subsequent requests
      security:
        - API_Key_1: []
  /notifications:
    post:
      summary: Publish a notification to the IE Runtime and/or IE Management UI(s)
      operationId: post-notifications
      responses:
        "204":
          description: "No Content: Notification successfully created"
        "400":
          description: |-
            Bad Request:
            - Unable to parse body data
            - Missing notification display name
            - Missing notification message
            - Invalid notification type
            - Invalid message type
            - Invalid operation name
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UnableToParseBodyDataError:
                  value:
                    errors:
                      - code: edge.unableToParseBodyData
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Invalid request body provided.
                MissingNotificationDisplayNameError:
                  value:
                    errors:
                      - code: edge.notifications.missingDisplayName
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Notification display name is missing.
                MissingNotificationMessageError:
                  value:
                    errors:
                      - code: edge.notifications.missingMessage
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Notification message is missing.
                InvalidNotificationTypeError:
                  value:
                    errors:
                      - code: edge.notifications.invalidNotificationType
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Notification type is invalid.
                InvalidMessageTypeError:
                  value:
                    errors:
                      - code: edge.notifications.invalidMessageType
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Message type is invalid.
                InvalidOperationNameError:
                  value:
                    errors:
                      - code: edge.notifications.invalidOperationName
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Operation name is invalid.
        "401":
          $ref: "#/components/responses/TokenError"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleInternalServerError:
                  $ref: "#/components/examples/InternalServerError"
        "503":
          description: "Service Unavailable: Job service not running"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ServiceNotRunningError:
                  $ref: "#/components/examples/ServiceNotRunning"
      description: |-
        - The details of the notification/alert are to be supplied via the request body parameter

        - If the notification/alert does not need to appear on the IEM UI, set the `sendToIEM` property of the payload to `false`

        **Note:**
        - A *400 Invalid Notification Type* error is returned, if the `notificationType` property in the payload is not one of specified enum values.
        - A *400 Invalid Message Type* error is returned, if the `messageType` property in the payload is not one of specified enum values.
        - A *400 Invalid Operation Name* error is returned, if the `sendToIEM` property in the payload is `true` and the supplied `operationName` is not one of specified enum values.
      tags:
        - notifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationDetails"
            examples:
              ExampleAddNotificationOnEdgeAndManagement:
                value:
                  displayName: Storage Alert
                  message: Not able to recover storage - please contact Support.
                  notificationType: Error
                  messageType: Storage
                  operationName: StorageStatistics
                  sendToIEM: true
              ExampleAddNotificationOnEdgeOnly:
                value:
                  displayName: You are invited to a new group.
                  message: New Group Invitation.
                  notificationType: Info
                  messageType: System
                  sendToIEM: false
        description: ""
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
  /check/dns-reachability:
    get:
      summary: Check the reachability from the Industrial Edge Device (IED) to the Industrial Edge Management (IEM) using the device's DNS configuration
      tags:
        - check
      operationId: check-dns-reachability
      description: |-
        This API evaluates DNS configuration to ensure its validity, assesses name resolution, and checks the reachability of the resulting Industrial Edge Management system address. Provides a result and status of all executed validation steps.

        This API's success does not ensure complete connectivity to the Industrial Edge Management system. Other configurations, such as proxy settings, network spoofing, or certificate issues, can also affect the results of the check and may influence communication during different system operations.

      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
        - name: detailed
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: specifies the detail level of the result.
      responses:
        "200":
          description: Successfully completed the reachability check to Industrial Edge Management (IEM).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DNSReachabilityResponse"
              examples:
                detailed:
                  $ref: "#/components/examples/dnsReachabilitySimpleExample"
                simple:
                  $ref: "#/components/examples/dnsReachabilityDetailedExample"
        "400":
          description: "Bad Request: Your request has invalid query parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InvalidQueryParamsError:
                  $ref: "#/components/examples/query-parameter-invalid-error"

        "401":
          description: "Unauthorized – Missing or invalid access token."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                expired-auth-header:
                  $ref: "#/components/examples/expired-auth-header"
                invalid-auth-header:
                  $ref: "#/components/examples/invalid-auth-header"
                unable-to-verify-auth-header:
                  $ref: "#/components/examples/unable-to-verify-auth-header"
                missing-auth-header:
                  $ref: "#/components/examples/missing-auth-header"
        "500":
          description: "Internal server error – something went wrong during the check."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"

  /check/http-reachability:
    get:
      summary: Performs http connectivity check from Industrial Edge Device (IED) to Industrial Edge Management (IEM).
      tags:
        - check
      operationId: check-http-reachability
      description: |-
        Performs a comprehensive HTTP reachability verification to the IEM(Industrial Edge Management).
        It includes validation of proxy server settings (if configured) and an HTTP request using certificates.
        The endpoint returns either basic or detailed results of each validation step to diagnose and identify potential connectivity issues.

        While the basic HTTP connectivity test passed, please note that complete system communication may be affected by
        other network components including Proxy configurations, Network security settings, and SSL/TLS certificate validation.

        It will use the IEM endpoint /chart-info as a reference.
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
        - name: detailed
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: specifies the detail level of the result.
      responses:
        "200":
          description: Successfully completed the reachability check to Industrial Edge Management (IEM).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IEMReachabilityResponse"
              examples:
                detailed:
                  $ref: "#/components/examples/iemReachabilitySimpleExample"
                simple:
                  $ref: "#/components/examples/iemReachabilityDetailedExample"
                detailedFailed:
                  $ref: "#/components/examples/iemReachabilityFailedDetailedExample"
                simpleFailed:
                  $ref: "#/components/examples/iemReachabilityFailedSimpleExample"

        "400":
          description: "Bad Request: Your request has invalid query parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InvalidQueryParamsError:
                  $ref: "#/components/examples/query-parameter-invalid-error"

        "401":
          description: "Unauthorized – Missing or invalid access token."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                expired-auth-header:
                  $ref: "#/components/examples/expired-auth-header"
                invalid-auth-header:
                  $ref: "#/components/examples/invalid-auth-header"
                unable-to-verify-auth-header:
                  $ref: "#/components/examples/unable-to-verify-auth-header"
                missing-auth-header:
                  $ref: "#/components/examples/missing-auth-header"
        "500":
          description: "Internal server error – something went wrong during the check."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"
  /check/tcp-reachability:
    post:
      summary: API endpoint for checking TCP connectivity from IED to data sources (PLCs, MQTT brokers, databases, data lakes, etc.)
      tags:
        - check
      operationId: check-tcp-reachability
      description: |-
        Performs a TCP connectivity check from the Industrial Edge Device (IED) to specified data sources such as PLCs, MQTT brokers, databases, or data lakes.
        This endpoint allows you to diagnose and identify potential network connectivity issues by attempting to establish TCP connections to a list of target hosts and ports.
        It returns either basic or detailed results for each connection attempt, indicating success, failure, and relevant diagnostic information like latency or error messages..

        This check helps identify issues such as unreachable hosts, blocked ports, connection timeouts, or connection refusals and verifies routing correctness as well
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
        - name: detailed
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: specifies the detail level of the result.
      requestBody:
        description: An object containing a list of target hosts and ports to check for TCP connectivity. Each target must specify a valid host (IP address or hostname) and a port number within the allowed range.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TCPDiagnoseRequest"
            examples:
              tcpDiagnoseRequestExample:
                $ref: "#/components/examples/tcpDiagnoseRequestExample"
      responses:
        "200":
          description: |-
            1. **Successful Response**: Successfully completed the TCP reachability check. The response contains the results for all specified targets, indicating their connection status.

            2. **Partial Response**: Partially successful TCP reachability check. This response indicates that the diagnostic process completed, but not all specified targets were tried due to Timeout Reached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TCPDiagnoseResponse"
              examples:
                detailed:
                  $ref: "#/components/examples/tcpDiagnoseSimpleExample"
                simple:
                  $ref: "#/components/examples/tcpDiagnoseDetailedExample"
                detailedFailed:
                  $ref: "#/components/examples/tcpDiagnoseDetailedWithErrorExample"
                simpleFailed:
                  $ref: "#/components/examples/tcpDiagnoseSimpleWithErrorExample"
                detailedPartialSuccess:
                  $ref: "#/components/examples/tcpDiagnoseDetailedWithPartialSuccessExample"
                simplePartialSuccess:
                  $ref: "#/components/examples/tcpDiagnoseSimpleWithPartialSuccessExample"
        "400":
          description: Bad Request - The request could not be processed due to invalid or malformed input, either in the request body or query parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                EmptyTargetsError:
                  $ref: "#/components/examples/emptyTarget"
                InvalidQueryParamsError:
                  $ref: "#/components/examples/invalidTcpTargetsQueryParam"
                invalidTcpTargetsRequestBody:
                  $ref: "#/components/examples/invalidTcpTargetsRequestBody"
                unableToParseTcpTargetsRequestBody:
                  $ref: "#/components/examples/unableToParseTcpTargetsRequestBody"
                tcpDiagnoseTooManyTargets:
                  $ref: "#/components/examples/tcpDiagnoseTooManyTargets"
                tcpDiagnoseInvalidPortRange:
                  $ref: "#/components/examples/tcpDiagnoseInvalidPortRange"
                tcpDiagnoseInvalidIpAddress:
                  $ref: "#/components/examples/tcpDiagnoseInvalidIpAddress"
                tcpDiagnoseIpv6NotSupported:
                  $ref: "#/components/examples/tcpDiagnoseIpv6NotSupported"
                tcpDiagnoseInvalidHost:
                  $ref: "#/components/examples/tcpDiagnoseInvalidHost"
                tcpDiagnoseNotaAllowed:
                  $ref: "#/components/examples/tcpDiagnoseNotaAllowed"

        "401":
          description: "Unauthorized – Missing or invalid access token."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                expired-auth-header:
                  $ref: "#/components/examples/expired-auth-header"
                invalid-auth-header:
                  $ref: "#/components/examples/invalid-auth-header"
                unable-to-verify-auth-header:
                  $ref: "#/components/examples/unable-to-verify-auth-header"
                missing-auth-header:
                  $ref: "#/components/examples/missing-auth-header"
        "429":
          description: "Too many requests – the client has sent too many requests in a given amount of time."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                TooManyRequestsError:
                  $ref: "#/components/examples/tooManyRequests"
        "500":
          description: "Internal server error – something went wrong during the check."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"
  /resources:
    get:
      summary: Get statistics data
      tags:
        - device
      responses:
        "200":
          description: Returns DeviceStatisticsVo in form of object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceStatisticsVo"
        "401":
          description: |-
            Returns Unauthorized errors -

              - Missing auth token
              - Invalid auth token
              - Expired auth token
              - Unable to verify auth token
              - Not permitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExpiredToken:
                  $ref: "#/components/examples/ExpiredToken"
                InvalidToken:
                  $ref: "#/components/examples/InvalidToken"
                TokenUserNotFound:
                  $ref: "#/components/examples/TokenUserNotFound"
                UnableToVerifyToken:
                  $ref: "#/components/examples/UnableToVerifyToken"
                MissingToken:
                  $ref: "#/components/examples/MissingToken"
                Not Permitted:
                  value:
                    errors:
                      - code: edge.notPermitted
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Access denied.
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleInternalServerError:
                  value:
                    errors:
                      - code: edge.internalServerError
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: The server encountered an unknown error.
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ServiceNotRunningError:
                  value:
                    errors:
                      - code: edge.serviceNotRunning
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Job service process is not running.
      operationId: get-resources
      description: |-
        This method returns storage and system information of edge device like:

          1. CPU info
           - coreCount
           - cpuArch
           - modelName
           - usedPercentage
           - freePercentage

          2. Memory info
           - free
           - total
           - used
           - usedPercentage
           - freePercentage

          3. Storage info
           - free
           - total
           - used
           - usedPercentage

          4. Uptime
      parameters:
        - $ref: "#/components/parameters/Authorization"
      security:
        - API_Key_1: []
  /applications/metrics:
    get:
      summary: Get statistics data
      tags:
        - device
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplicationMetrics"
        "401":
          description: |-
            Unauthorized:
            - Expired token
            - Invalid token
            - Missing token
            - Token user not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleExpiredTokenError:
                  $ref: "#/components/examples/ExpiredToken"
                ExampleInvalidTokenError:
                  $ref: "#/components/examples/InvalidToken"
                ExampleTokenUserNotFound:
                  $ref: "#/components/examples/TokenUserNotFound"
                ExampleMissingToken:
                  $ref: "#/components/examples/MissingToken"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ExampleInternalServerError:
                  $ref: "#/components/examples/InternalServerError"
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ServiceNotRunningError:
                  $ref: "#/components/examples/ServiceNotRunning"
      operationId: get-application-metrics
      description: "This API provides the application statistics, such as application state, memory, and CPU usage. this API is used by Metrics Agent to get the application metrics."
      parameters:
        - $ref: "#/components/parameters/Authorization"
    parameters: []
  /shutdown:
    post:
      tags:
        - device
      summary: Shutdown Edge Core
      operationId: post-shutdown
      responses:
        "204":
          description: "No Content: Device shutdown successfully."
        "400":
          description: |-
            Bad Request:
            - Invalid Request Body Parameter
            - Invalid MaxAck Time
            - No Supported
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Invalid Request Body Parameter:
                  $ref: "#/components/examples/InvalidRequestBody"
                Invalid MaxAck Time For Apps:
                  $ref: "#/components/examples/AckTimeRangeNotAcceptable"
                Not Supported:
                  value:
                    errors:
                      - code: edge.notsupported
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Not supported.
        "401":
          description: |-
            Unauthorized:
            - Missing the Auth Token
            - Invalid Auth Token
            - Expired Auth Token
            - User of the Auth Token was not Found
            - Unable to Verify Auth Token
            - Not permitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Expired Token:
                  $ref: "#/components/examples/ExpiredToken"
                Invalid Token:
                  $ref: "#/components/examples/InvalidToken"
                Missing Token:
                  $ref: "#/components/examples/MissingToken"
                Token User Not Found:
                  $ref: "#/components/examples/TokenUserNotFound"
                Unable To verify Token:
                  $ref: "#/components/examples/UnableToVerifyToken"
                Not Permitted:
                  value:
                    errors:
                      - code: edge.notPermitted
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Access denied.
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Internal Server Error:
                  $ref: "#/components/examples/InternalServerError"
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Service Not Running Error:
                  $ref: "#/components/examples/ServiceNotRunning"
      description: |-
        This method performs shutdown of the edge device on the basis of 'maxAckTimeForApps' and 'executeNow' parameters.


        **Note**:
          - A *400 Bad request* error will be returned, if `maxAckTimeForApps ` value does not match according to the parameter (`0 < maxAckTimeForApps <= 30`) or invalid body parameter passed.
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GracefulShutdownParameter"
            examples:
              GracefulShutdownParam:
                value:
                  maxAckTimeForApps: 30
                  executeNow: true
        description: "- `executeNow` and `maxAckTimeForApps ` parameter value will come from privileged app and on the basis of this parameters graceful shutdown of the device decision will be taken."
      security:
        - API_Key_1: []
  /info:
    get:
      summary: Get Device Information data
      tags:
        - device
      responses:
        "200":
          description: |
            This retrieves the device related information.</br>

            **Note:** This API supports multiple response examples based on the device state (before/after onboarding) and available data (with/without layer-2 network data and /etc/system-info file). </br>
              - L2 attributes: l2Ipv4, l2SubnetMask and l2Gateway will be available only if layer-2 network is configured on the device.
              - Before onboarding the device, deviceName and deviceId will not be present in the response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceInfo"
              examples:
                detailed:
                  $ref: "#/components/examples/deviceinfodetailed"
                beforeonboardingwithL2:
                  $ref: "#/components/examples/deviceInfoBeforeOnboardingWithLayer-2"
                beforeonboardingwithoutL2:
                  $ref: "#/components/examples/deviceInfoBeforeOnboardingWithoutLayer-2"
                afteronboardingwithoutL2:
                  $ref: "#/components/examples/deviceInfoAfterOnboardingWithoutLayer-2"
                afteronboardingwithL2:
                  $ref: "#/components/examples/deviceInfoAfterOnboardingWithLayer-2"
                beforeonboardingwithoutSystemInfoFile:
                  $ref: "#/components/examples/deviceInfoBeforeOnboardingWithoutSystemInfoFile"
                afteronboardingwithoutSystemInfoFile:
                  $ref: "#/components/examples/deviceInfoAfterOnboardingWithoutSystemInfoFile"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
      operationId: get-info
      description: |-
        description: |-
         This method returns device information of edge device like:

         **Property Details:**
         | Property Name(s) | IEDK Version |
         |------------------|--------------|
         | deviceId, deviceName | 1.26.0+ |
         | networks (interfaceName,ipAddress,subnetMask, gateway, l2IPv4, l2SubnetMask, l2Gateway, macAddress) | 1.26.0+  |
         | manufacturerName, serialNumber, productId, firmwareVersion, productName, biosVersion | 1.27.0+  |
  /hostname:
    get:
      summary: Retrieve the hostname of the IE Runtime device.
      tags:
        - device
      responses:
        "200":
          description: Successfully retrieved the hostname.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostName"
              examples:
                GetHostName:
                  value:
                    hostname: edge-runtime-01
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                expired-auth-header:
                  $ref: "#/components/examples/expired-auth-header"
                invalid-auth-header:
                  $ref: "#/components/examples/invalid-auth-header"
                unable-to-verify-auth-header:
                  $ref: "#/components/examples/unable-to-verify-auth-header"
                missing-auth-header:
                  $ref: "#/components/examples/missing-auth-header"
        "500":
          description: Something went wrong
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                service-not-running:
                  $ref: "#/components/examples/service-not-running"
      operationId: get-hostname
      description: |-
        This API retrieves the hostname of IED.
        The request must include a valid authorization token in the header.
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
    put:
      summary: Update the hostname of the IE Runtime device.
      tags:
        - device
      responses:
        "204":
          description: "The hostname was successfully updated. This operation does not return any response body, as indicated by the 204 No Content status."
        "400":
          description: Invalid input for hostname update.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                invalid-request-body:
                  $ref: "#/components/examples/invalid-request-body"
                invalid-hostname:
                  $ref: "#/components/examples/invalid-hostname"
                invalid-hostname-length-exceeds-limit:
                  $ref: "#/components/examples/invalid-hostname-length-exceeds-limit"
                invalid-hostname-length-below-limit:
                  $ref: "#/components/examples/invalid-hostname-length-below-limit"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                expired-auth-header:
                  $ref: "#/components/examples/expired-auth-header"
                invalid-auth-header:
                  $ref: "#/components/examples/invalid-auth-header"
                unable-to-verify-auth-header:
                  $ref: "#/components/examples/unable-to-verify-auth-header"
                missing-auth-header:
                  $ref: "#/components/examples/missing-auth-header"
        "403":
          description: "Forbidden, User has a valid authorization token but don't have admin rights."
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Forbidden-errors:
                  $ref: "#/components/examples/forbidden-auth-error"
        "500":
          description: Something went wrong
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"
        "503":
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                service-not-running:
                  $ref: "#/components/examples/service-not-running"
      operationId: put-hostname
      description: |-
        This endpoint updates the hostname of the IED.
        The request must include a valid authorization token in the header.
        The new hostname should be provided in the request body.
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
      requestBody:
        description: An object that contains the new hostname to be configured for the device. The hostname must meet the required format and length specifications to ensure proper device identification.
        content:
          application/json:
            schema:
              description: ""
              type: object
              properties:
                hostname:
                  type: string
                  pattern: '^[A-Za-z0-9]([A-Za-z0-9-]{0,62}[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]{0,62}[A-Za-z0-9])?)*$'
                  minLength: 1
                  maxLength: 63
              required:
                - hostname
            examples:
              UpdateHostname:
                value:
                  hostname: edge-runtime-01
    parameters: []
  /system-use-notification:
    get:
      summary: Retrieves the current system notification message and its display status configured on the Industrial Edge Runtime.
      tags:
        - device
      responses:
        "200":
          description: Successfully retrieved the system notification message.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemUseNotificationRequest"
              example:
                systemUseNotification:
                  message: System maintenance scheduled at 10 PM.
                  enabled: true
        "400":
          description: Edge device is not onboarded yet.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                edge-device-not-onboarded:
                  $ref: "#/components/examples/edge-device-not-onboarded-error"
        "500":
          description: Something went wrong
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"

      operationId: get-system-use-notification
      description: |-
        This API retrieves the current system notification message and its display status configured for the Industrial Edge Runtime.
        The message is typically displayed to users to provide announcements.
      parameters:
        - $ref: "#/components/parameters/X-Correlation-ID"
    put:
      summary: Updates the system notification message configured for display on the Industrial Edge Runtime.
      tags:
        - device
      responses:
        "204":
          description: "The system notification message successfully updated.This operation does not return any response body, as indicated by the 204 No Content status."
        "400":
          description: Invalid input (e.g., exceeds 300 characters or contains disallowed characters).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                invalid-request-body:
                  $ref: "#/components/examples/invalid-system-notification-request-body"
                unable-to-parse-request-body:
                  $ref: "#/components/examples/unable-to-parse-request-body"
                invalid-system-notification-message:
                  $ref: "#/components/examples/invalid-system-notification"
                invalid-system-message-length-exceeds-limit:
                  $ref: "#/components/examples/invalid-system-message-length-exceeds-limit"
                invalid-system-notification-message-required:
                  $ref: "#/components/examples/invalid-system-notification-message-required"
                invalid-system-notification-no-change:
                  $ref: "#/components/examples/invalid-system-notification-no-change"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                expired-auth-header:
                  $ref: "#/components/examples/expired-auth-header"
                invalid-auth-header:
                  $ref: "#/components/examples/invalid-auth-header"
                unable-to-verify-auth-header:
                  $ref: "#/components/examples/unable-to-verify-auth-header"
                missing-auth-header:
                  $ref: "#/components/examples/missing-auth-header"
        "403":
          description: "Forbidden, User has a valid authorization token but don't have admin rights."
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Forbidden-error:
                  $ref: "#/components/examples/forbidden-auth-error_for-update-system-notification"
        "500":
          description: Something went wrong
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error-response"
              examples:
                something-went-wrong:
                  $ref: "#/components/examples/something-went-wrong"
      operationId: put-system-use-notification
      description: |-
        This API allows an administrator to update the system notification message shown on the Industrial Edge Runtime.
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
      requestBody:
        description: An object that contains the system notification message and its enabled status. The message must meet the required format and length specifications.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SystemUseNotificationRequest"
            examples:
              UpdateSystemNotification:
                summary: Enable system notification with a valid message
                value:
                  systemUseNotification:
                    message: System maintenance scheduled at 10 PM.
                    enabled: true
  /networks/{interfaceName}/status:
    get:
      summary: Provides health status of network interface of IE Runtime device.
      tags:
        - networks
      responses:
        "200":
          description: Successfully retrieved the network status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShowNetworkStatus"
              examples:
                ConnectedStatus:
                  summary: GSM Connection Success
                  value:
                    interfaceName: cdc-wdm0
                    ipAddress: 100.72.168.142
                    subnetMask: 255.255.255.252
                    status: Enabled
                    gateway: 100.72.168.141
                    primaryDns: 117.96.122.106
                    secondaryDns: 202.56.215.41
                    hostName: localhost
                    isDhcp: true
                    isEnabled: true
                    isInternetOn: true
                    dockerIp: 10.0.0.0/16
                    gatewayInterface: true
                    interfaceType: GSM
                    gsmConfig:
                      apn: airtelgprs.com
                      userName: airtel
                    connectionStatus:
                      updatedAt: "2026-06-19T09:22:11Z"
                      connectionState: CONNECTED
                      connectionFailedReason: "No error"
                      gsm:
                        accessTechnology: 4G
                        signalQualityPercent: 72
                        operatorName: Airtel
                        operatorCode: "40445"
                        registrationState: REGISTERED
                        roamingState: HOME
                        bearerConnected: true
                SIMLocked:
                  summary: GSM Connection SIM Locked
                  value:
                    interfaceName: cdc-wdm0
                    gatewayInterface: false
                    interfaceType: GSM
                    connectionStatus:
                      updatedAt: "2026-06-19T09:22:11Z"
                      connectionState: SIM_LOCKED
                      connectionFailedReason: "No error"
                      gsm:
                        accessTechnology: UNSPECIFIED
                        registrationState: UNSPECIFIED
                        roamingState: UNSPECIFIED
                ErrorStatus:
                  summary: GSM Connection Error or Disconnected
                  value:
                    interfaceName: cdc-wdm0
                    interfaceType: GSM
                    gatewayInterface: false
                    connectionStatus:
                      updatedAt: "2026-06-19T09:25:43Z"
                      connectionState: DISCONNECTED
                      connectionFailedReason: "SIM is missing"
                      gsm:
                        accessTechnology: UNSPECIFIED
        "400":
          description: |-
            Bad Request; Interface type not supported for status monitoring.
              - Network Interface type not supported.
              - Device is not capable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDetailed"
              examples:
                InterfaceTypeNotSupported:
                  $ref: "#/components/examples/NetworkInterfaceTypeNotSupported"
                CellularNotCapableError:
                  $ref: "#/components/examples/CellularNotCapableError"
        "401":
          description: |-
            Returns Unauthorized errors -
              - Missing auth token
              - Invalid auth token
              - Expired auth token
              - Unable to verify auth token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDetailed"
              examples:
                ExpiredToken:
                  $ref: "#/components/examples/ExpiredTokenDetailed"
                InvalidToken:
                  $ref: "#/components/examples/InvalidTokenDetailed"
                UnableToVerifyToken:
                  $ref: "#/components/examples/UnableToVerifyTokenDetailed"
                MissingToken:
                  $ref: "#/components/examples/MissingTokenDetailed"
        "404":
          description: "Not Found: Network interface not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDetailed"
              examples:
                NetworkInterfaceNotFound:
                  $ref: "#/components/examples/NetworkInterfaceNotFound"
        "429":
          description: Too many requests; the client has sent too many requests in a given amount of time.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDetailed"
              examples:
                TooManyRequestsError:
                  $ref: "#/components/examples/too-many-requests-error"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDetailed"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerErrorDetailed"
        "503":
          description: "Service Unavailable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseDetailed"
              examples:
                NetworkServiceNotRunning:
                  $ref: "#/components/examples/NetworkServiceNotRunningDetailed"

      operationId: get-network-status
      description: |-
        Enables users to monitor network health across available interfaces by exposing connection status, network quality metrics, carrier or link details, and IP/DNS/gateway information.

        This status information can be used for faster
        diagnostics and proactive issue handling.
      security:
        - API_Key_1: []
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/X-Correlation-ID"
        - $ref: "#/components/parameters/interfaceName"
components:
  schemas:
    Login:
      type: object
      properties:
        username:
          type: string
          description: Associated user name for basic auth
        password:
          type: string
          format: password
          description: Associated password for basic auth
        verificationCode:
          type: string
      required:
        - username
        - password

    CertInfo:
      type: object
      properties:
        issuer:
          type: string
        cn:
          type: string
        san:
          type: string
        validity:
          type: string
    ConnectInfo:
      type: object
      properties:
        latency:
          type: string
        transferredData:
          type: string
    Attempt:
      type: object
      properties:
        destIp:
          type: string
        id:
          type: integer
        statusCode:
          type: integer
        error:
          type: string
        tlsError:
          type: string
        connectionInfo:
          $ref: "#/components/schemas/ConnectInfo"
        Response:
          type: string
        certInfo:
          type: array
          items:
            $ref: "#/components/schemas/CertInfo"
    ConnectionDetail:
      type: object
      properties:
        server:
          type: string
        response:
          type: string
        attemptCount:
          type: integer
        attempts:
          type: array
          items:
            $ref: "#/components/schemas/Attempt"
      required:
        - server
        - response
        - attemptCount
        - attempts
    HostName:
      type: object
      title: HostName
      properties:
        hostname:
          type: string
          description: The hostname of the IE Runtime device
      required:
        - hostname
    SystemUseNotificationRequest:
      type: object
      title: SystemUseNotificationRequest
      properties:
        systemUseNotification:
          type: object
          title: SystemNotification
          properties:
            message:
              type: string
              description: System notification message for the IE Runtime device
              pattern: "^[a-zA-Z0-9 ._:-]*$"
              minLength: 0
              maxLength: 300
            enabled:
              type: boolean
              description: |
                Indicates whether the system notification is enabled or not.
                If set to false, the message will not be displayed, regardless of whether a valid message is provided.
                In this case, the `enabled` flag takes precedence, and the `message` field will be ignored.
          required:
            - enabled
      required:
        - systemUseNotification
    ApplicationMetrics:
      title: ApplicationMetrics
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: "#/components/schemas/ApplicationMetricsVO"
    ApplicationMetricsVO:
      type: object
      title: ApplicationMetricsVO
      example:
        applicationState: Running
        imagesCount: 7
        memory: 48156672
        cpuUsage: 0.09
        versionId: f4HGiIK8Vy3jg8WYAqXPDLlshAJ0Kxxu
        version: 3.2.2-1
        companyName: Siemens AG
        applicationId: cc44551050f2406780710fa9ff013451
        projectId: d4f9b1e0f2a2429a9d44eb9c872845ea
        userId: f8dd4206b24f4f108ceb81e0159f4faf
        icon: "https://localhost:443/device/edge/BoxCache/app/cc44551050f2406780710fa9ff013451/appicon.png"
        title: Databus
        repoName: db
        appStatus: ACTIVE
        isDeveloperAppInstall: true
        description: Databus
      description: Used to hold details of the application metrics.
      properties:
        appStatus:
          type: string
          description: "Displayed the application status like ACTIVE, SUSPENDED, FAILED."
          example: ACTIVE
        applicationId:
          type: string
          description: The used application Id.
        applicationState:
          type: string
          description: Displayed the application state like Running/Stopped.
          example: Running
        companyName:
          type: string
          description: The application used company name.
        companyWebAddress:
          type: string
          description: The application used company webAddress.
        cpuUsage:
          type: number
          description: The application CPU usage.
        description:
          type: string
          description: Displayed the application description.
        icon:
          type: string
          description: The application icon path.
        imagesCount:
          type: number
          description: The application used number of images.
        isDeveloperAppInstall:
          type: boolean
          description: The application is developerapp.
        memory:
          type: number
          description: The application used memory.
        projectId:
          type: string
          description: The application used projectId.
        repoName:
          type: string
          description: Displayed the application repoName.
        title:
          type: string
          description: Displayed the application title.
        userId:
          type: string
          description: Displayed the application userId.
        version:
          type: string
          description: The application created version.
        versionId:
          type: string
          description: The application created versionId.
    LoginResponse:
      type: object
      properties:
        accessToken:
          type: string
          format: uuid
        expiresAt:
          type: integer
          description: Time stamp in seconds
          example: 1678726923
    Error:
      title: Error
      type: object
      description: Error consist of code which is associated with message and logref which is a uuid, used to distinctly identify the error.
      properties:
        code:
          type: string
          minLength: 2
        logref:
          type: string
          format: uuid
          minLength: 1
          description: Unique uuid generated for each error
        message:
          type: string
          minLength: 1
      required:
        - code
        - message
    Error-response:
      title: Error
      type: object
      description: "Error consist of code which is associated with message and logref which is a uuid, used to distinctly identify the error."
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                minLength: 2
              status:
                type: integer
                format: uuid
                description: Unique uuid generated for each error
              title:
                type: string
                minLength: 1
              correlationId:
                type: string
            required:
              - code
              - title
    ErrorResponseDetailed:
      title: Error
      type: object
      description: "An array of structured error objects, each containing an error code, HTTP status code, human-readable title, optional detail message, and a correlationId UUID for tracing the error."
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                minLength: 2
              status:
                type: integer
                format: int32
                description: HTTP status code associated with the error
              title:
                type: string
                minLength: 1
              message:
                type: string
                minLength: 1
              correlationId:
                type: string
                format: uuid
            required:
              - code
              - title
              - status
    ErrorResponse:
      title: ErrorResponse
      description: An array of the error model, hence allowing response on single as well as multiple errors
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
    NotificationDetails:
      title: NotificationDetails
      type: object
      description: Used to hold details of the notification/alert to be displayed on IE Runtime and/or IEM UI(s)
      properties:
        displayName:
          type: string
          description: Title of the notification/alert
          example: Certificate updated.
        message:
          type: string
          description: Actual notification/alert message
          example: Certificates update successfully
        notificationType:
          type: string
          description: The category of notification/alert & this category is used by the IE-Runtime UI to filter notifications
          enum:
            - Warning
            - Error
            - Info
            - Critical
          example: Info
        messageType:
          type: string
          description: The category of notification/alert message & this category is used by the IE-Runtime UI to filter notifications
          example: System
          enum:
            - System
            - CPU
            - Memory
            - Storage
            - Connectivity
            - Apps
            - Users
        operationName:
          type: string
          description: The category of notification/alert related operation & this category is used by the IE-Management UI to filter notifications
          example: CertificateUpdate
          enum:
            - CertificateUpdate
            - StorageStatistics
            - CertificateExpire
            - AppUpdate
            - FirmwareUpdate
            - CPUStatistics
            - MemoryStatistics
            - NetworkStatistics
            - AppCrash
            - AppJobStatus
            - DeviceStatus
        sendToIEM:
          type: boolean
          description: Indicates if the notification/alert is to be sent to IE Management as well
      required:
        - displayName
        - message
        - notificationType
        - messageType
    DeviceStatisticsVo:
      description: ""
      type: object
      example:
        cpu:
          usedPercentage: 99%
          coreCount: "2"
          modelName: Intel(R) Core(TM) i7-8700T CPU @ 2.40GHz
          cpuArch: x86_64
          freePercentage: 1%
        storage:
          total: 53.1 GB
          used: 10.2 GB
          free: 40.6 GB
          usedPercentage: 19.27%
        memory:
          total: 7.8 GB
          used: 4.9 GB
          free: 3.1 GB
          usedPercentage: 63.61%
          freePercentage: 36.39%
        upTime: 1 days, 20 hours, 13 minutes
      properties:
        cpu:
          type: object
          properties:
            usedPercentage:
              type: string
              description: CPU used space in percentage
            coreCount:
              type: string
              description: Total number of CPU cores
            modelName:
              type: string
              description: Full processor details including model name
            cpuArch:
              type: string
              description: Architectural bit version details
            freePercentage:
              type: string
              description: Free cpu space in percentage
        storage:
          type: object
          properties:
            free:
              type: string
              description: Free storage space in GB
            usedPercentage:
              type: string
              description: Used storage space in percentage
            total:
              type: string
              description: Total storage space in GB
            used:
              type: string
              description: Used storage space in GB
        memory:
          type: object
          properties:
            total:
              type: string
              description: Total memory space in GB
            free:
              type: string
              description: Free memory space in GB
            used:
              type: string
              description: Used memory space in GB
            usedPercentage:
              type: string
              description: Used memory space in percentage
            freePercentage:
              type: string
              description: Free memory space in percentage
        upTime:
          type: string
          description: Last uptime detail of device
    DeviceInfo:
      description: |
        'This retrieves the device related information.

        Note: This specification is compatible with edge-iot-core-container version 1.25.0.7 and later, and Properties from manufacturerName, serialNumber, productId, firmwareVersion, productName and biosVersion are available from version 1.27 onward.'
      type: object
      example:
        deviceId: d796e233cf794b028ec945efce00f24d
        deviceName: myEdgeDevice
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            l2IPv4: 192.168.182.0
            l2SubnetMask: 255.255.254.0
            l2Gateway: 192.168.182.1
            macAddress: 00:0C:29:83:54:A5
        manufacturerName: Siemens
        serialNumber: S159765215
        productId: 6ES7647-8BD31-0CW1
        firmwareVersion: simatic-ipc-ied-os-v3.0.0-51
        productName: SIMATIC IPC227G
        biosVersion: S5C620.86B.01.01.0016.082920171234
      properties:
        deviceId:
          type: string
          description: Unique Id of the device
        deviceName:
          type: string
          description: Name of the device
        networks:
          type: array
          description: List of network interfaces
          items:
            type: object
            properties:
              interfaceName:
                type: string
                description: Name of network interface
              ipAddress:
                type: string
                description: Ip address of the interface
              subnetMask:
                type: string
                description: SubnetMask of the interface
              gateway:
                type: string
                description: Gateway of the interface
              l2IPv4:
                type: string
                description: Layer2 Ip of the interface
              l2SubnetMask:
                type: string
                description: Layer2 SubnetMask of the interface
              l2Gateway:
                type: string
                description: Layer2 Gateway of the interface
              macAddress:
                type: string
                description: Mac Address of the interface
        manufacturerName:
          type: string
          description: Manufacturer name of the device
        serialNumber:
          type: string
          description: Serial number of the device
        productId:
          type: string
          description: Product ID of the device
        firmwareVersion:
          type: string
          description: Firmware version of the device
        productName:
          type: string
          description: Product name of the device
        biosVersion:
          type: string
          description: BIOS version of the device
    GracefulShutdownParameter:
      title: GracefulShutdownParameter
      type: object
      properties:
        maxAckTimeForApps:
          type: number
          minimum: 1
          maximum: 30
          description: |
            if executeNow = `true` then it will look for the `maxAckTimeForApps` in the body parameters.
            if `maxAckTimeForApps` parameter is not present in the body parameters, then it will throw an error.
        executeNow:
          type: boolean
          default: false
          description: |-
            if executeNow = `false`, then it will add the job in the job manager and will read the value from `eventCommunicationTimeout` and performs the shutdown process.

            if executeNow = `true`, then the value will be taken from the `maxAckTimeForApps` which is coming in body parameters and then performs the graceful shutdown.
    DNSReachabilityResponse:
      type: object
      properties:
        dnsReachability:
          type: object
          properties:
            status:
              type: string
              enum: [OK, FAILED]
            executionError:
              type: string
            results:
              type: object
              properties:
                dnsServerResponsive:
                  type: object
                  properties:
                    status:
                      type: integer
                    details:
                      type: array
                      items:
                        type: object
                        properties:
                          server:
                            type: string
                            format: ipv4
                          response:
                            type: string
                domainResolution:
                  type: object
                  properties:
                    status:
                      type: integer
                    details:
                      type: array
                      items:
                        type: object
                        properties:
                          domain:
                            type: string
                            format: hostname
                          dnsServer:
                            type: string
                            format: ipv4
                          status:
                            type: string
                            enum: [OK, FAILED]
                          error:
                            type: string
                          dnsResolutionInfo:
                            type: string
                          resolvedIps:
                            type: array
                            items:
                              type: string
                              format: ipv4
                reachDomainAddress:
                  type: object
                  properties:
                    status:
                      type: integer
                    details:
                      type: array
                      items:
                        type: object
                        properties:
                          domain:
                            type: string
                          status:
                            type: string
                            enum: [OK, FAILED]
                          error:
                            type: string
                          ipChecks:
                            type: array
                            items:
                              type: object
                              properties:
                                ipAddress:
                                  type: string
                                  format: ipv4
                                error:
                                  type: string
                                response:
                                  type: string
    IEMReachabilityResponse:
      properties:
        iemReachability:
          type: object
          properties:
            status:
              type: string
              enum: [OK, FAILED]
            executionError:
              type: string
            results:
              type: object
              properties:
                proxyServerResponsive:
                  type: object
                  properties:
                    status:
                      type: integer
                    details:
                      type: array
                      items:
                        type: object
                        properties:
                          server:
                            type: string
                          response:
                            type: string
                          attemptCount:
                            type: integer
                          attempts:
                            type: array
                            items:
                              $ref: "#/components/schemas/Attempt"
                serverEndPointResponsive:
                  type: object
                  properties:
                    status:
                      type: integer
                    details:
                      type: array
                      items:
                        type: object
                        properties:
                          server:
                            type: string
                          response:
                            type: string
                          attemptCount:
                            type: integer
                          attempts:
                            type: array
                            items:
                              $ref: "#/components/schemas/Attempt"
    TCPDiagnoseResponse:
      type: object
      properties:
        tcpReachability:
          type: object
          properties:
            status:
              type: string
              enum: [OK, FAILED]
              description: The overall status of the TCP diagnosis.
            executionError:
              type: string
              description: Any error message if the diagnosis execution failed.
            results:
              type: object
              properties:
                tcpConnection:
                  $ref: "#/components/schemas/TCPConnectionDetails"

    TCPConnectionDetails:
      type: object
      properties:
        status:
          type: integer
          description: Numeric status of the TCP connection check (e.g., 1 for success, 0 for failure/partial failure).
        details:
          type: array
          items:
            $ref: "#/components/schemas/ConnectionAttempt"

    ConnectionAttempt:
      type: object
      properties:
        host:
          type: string
          description: The hostname or IP address that was attempted to connect to.
        port:
          type: integer
          format: int32
          description: The port number used for the connection attempt.
        status:
          type: string
          enum: [OK, FAILED]
          description: The status of this specific connection attempt.
        response:
          type: string
          description: A detailed response message for the connection attempt (present for OK status).
        latency:
          type: integer
          format: int32
          description: The latency of the connection in milliseconds (present for OK status).
        error:
          type: string
          description: An error message if the connection attempt failed (present for FAILED status).
        errorCategory:
          type: string
          enum: [DNS, Network, Unknown, DeadlineExceeded]
          description: The category of the error (e.g., DNS, Network, Unknown) (present for FAILED status).
      required:
        - host
        - port
        - status
      # 'response' and 'latency' are optional (for FAILED status)
      # 'error' and 'errorCategory' are optional (for OK status)
    TCPDiagnoseRequest:
      type: object
      properties:
        targets:
          type: array
          description: A list of host and port combinations to perform TCP connection checks against.
          items:
            $ref: "#/components/schemas/ConnectionTarget"
      required:
        - targets

    ConnectionTarget:
      type: object
      properties:
        host:
          type: string
          description: The hostname or IP address of the target.
          example: "192.168.1.10"
        port:
          type: integer
          format: int32
          description: The port number to connect to on the target.
          example: 502
      required:
        - host
        - port
    ShowNetworkStatus:
      title: ShowNetworkStatus
      type: object
      example:
        interfaceName: cdc-wdm0
        ipAddress: 100.72.168.142
        subnetMask: 255.255.255.252
        status: Enabled
        gateway: 100.72.168.141
        primaryDns: 117.96.122.106
        secondaryDns: 202.56.215.41
        hostName: localhost
        isDhcp: true
        isEnabled: true
        isInternetOn: true
        dockerIp: 10.0.0.0/16
        gatewayInterface: true
        interfaceType: GSM
        gsmConfig:
          apn: airtelgprs.com
          userName: airtel
        connectionStatus:
          updatedAt: "2026-06-19T09:22:11Z"
          connectionState: CONNECTED
          connectionFailedReason: UNSPECIFIED
          gsm:
            accessTechnology: 4G
            signalQualityPercent: 72
            operatorName: Airtel
            operatorCode: "40445"
            registrationState: REGISTERED
            roamingState: HOME
            bearerConnected: true
      properties:
        interfaceName:
          type: string
          description: Display the interface name.
        interfaceType:
          type: string
          description: Type of the network interface.
          enum:
            - ETHERNET
            - GSM
        ipAddress:
          type: string
          description: IP address assigned to the interface.
        subnetMask:
          type: string
          description: Subnet mask assigned to the interface.
        gateway:
          type: string
          description: Gateway address for the interface.
        primaryDns:
          type: string
          description: Primary DNS server address.
        secondaryDns:
          type: string
          description: Secondary DNS server address.
        status:
          type: string
          description: Current administrative status of the interface.
        hostName:
          type: string
          description: Hostname associated with the network configuration.
        isDhcp:
          type: boolean
          description: Indicates whether DHCP is enabled on this interface.
        isEnabled:
          type: boolean
          description: Indicates whether this interface is enabled.
        isInternetOn:
          type: boolean
          description: Indicates whether internet connectivity is currently available.
        dockerIp:
          type: string
          description: Docker bridge network CIDR used by the device.
        gatewayInterface:
          type: boolean
          description: Indicates if this is the gateway interface.
        gsmConfig:
          type: object
          properties:
            apn:
              type: string
              description: Access Point Name in use
            userName:
              type: string
              description: APN authentication username
        connectionStatus:
          type: object
          properties:
            updatedAt:
              type: string
              format: date-time
              description: Timestamp when the network status was last updated.
            connectionState:
              type: string
              description: Overall connectivity state of the GSM interface
              enum:
                - UNSPECIFIED
                - CONNECTED
                - CONNECTING
                - DISCONNECTED
                - ERROR
                - NO_MODEM
                - SIM_LOCKED
            connectionFailedReason:
              type: string
              description: Reason why the interface is disconnected. Populated only when the connectionState is DISCONNECTED, otherwise it is unset/No error.
              example: "SIM is missing"
            gsm:
              type: object
              description: GSM-specific connection and carrier telemetry.
              properties:
                accessTechnology:
                  type: string
                  description: Radio access technology currently in use
                  enum:
                    - UNSPECIFIED
                    - 2G
                    - 3G
                    - 4G
                    - 5G
                signalQualityPercent:
                  type: integer
                  minimum: 0
                  maximum: 100
                  description: Raw signal quality from ModemManager
                operatorName:
                  type: string
                  description: Full name of the registered cellular carrier
                operatorCode:
                  type: string
                  description: Raw PLMN code (MCC+MNC concatenated). e.g- "26202" (MCC=262, MNC=02)
                registrationState:
                  type: string
                  description: 3GPP network registration state
                  enum:
                    - UNSPECIFIED
                    - REGISTERED
                    - SEARCHING
                    - DENIED
                    - IDLE
                roamingState:
                  type: string
                  description: Indicates home vs. roaming network
                  enum:
                    - UNSPECIFIED
                    - HOME
                    - ROAMING
                bearerConnected:
                  type: boolean
                  description: Whether a data bearer (PDP context) is established
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: Authorization token
    X-Correlation-ID:
      name: X-Correlation-ID
      in: header
      required: false
      schema:
        type: string
      description: Correlates logs
    interfaceName:
      name: interfaceName
      in: path
      required: true
      schema:
        type: string
      description: Network interface name
  examples:
    ExpiredToken:
      value:
        errors:
          - code: edge.auth.expiredToken
            title: Token expired.
            message: Token expired.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    ExpiredTokenDetailed:
      value:
        errors:
          - code: edge.auth.expiredToken
            title: Token expired.
            message: Token expired.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
            status: 401
    InvalidToken:
      value:
        errors:
          - code: edge.auth.invalidToken
            title: Token is invalid.
            message: Token is invalid.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    InvalidTokenDetailed:
      value:
        errors:
          - code: edge.auth.invalidToken
            title: Token is invalid.
            message: Token is invalid.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
            status: 401
    TokenUserNotFound:
      value:
        errors:
          - code: auth.application.userNotFound
            title: User not found.
            message: User not found.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    UnableToVerifyToken:
      value:
        errors:
          - code: auth.token.unableToVerifyToken
            title: Unable to verify token.
            message: Unable to verify token.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    UnableToVerifyTokenDetailed:
      value:
        errors:
          - code: auth.token.unableToVerifyToken
            title: Unable to verify token.
            message: Unable to verify token.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
            status: 401
    MissingToken:
      value:
        errors:
          - code: edge.auth.missingToken
            title: Token is required.
            message: Token is required.
            logref: 3505f6bd-30cd-4deb-981d-02e89f82aa8f
    MissingTokenDetailed:
      value:
        errors:
          - code: edge.auth.missingToken
            title: Token is required.
            message: Token is required.
            correlationId: 3505f6bd-30cd-4deb-981d-02e89f82aa8f
            status: 401
    NotPermitted:
      value:
        errors:
          - code: edge.notPermitted
            title: Access denied.
            message: Access denied.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    InvalidRequestBody:
      value:
        errors:
          - code: edge.job.invalidRequestBody
            message: Invalid request body.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    SystemCommandRunning:
      value:
        errors:
          - code: edge.SystemCommandRunning
            message: System command is running, cannot perform requested operation.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    ServiceNotRunning:
      value:
        errors:
          - code: edge.serviceNotRunning
            message: Job service process is not running.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    InvalidCommand:
      value:
        errors:
          - code: edge.job.invalidCommand
            message: Invalid command provided.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    InternalServerError:
      value:
        errors:
          - code: edge.internalServerError
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: The server encountered an unknown error.
    InternalServerErrorDetailed:
      value:
        errors:
          - code: edge.internalServerError
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
            status: 500
            title: Internal Server Error
            message: The server encountered an unknown error.
    AckTimeRangeNotAcceptable:
      value:
        errors:
          - code: edge.device.invalidAckTimeRange
            logref: c105072b-39cb-49d9-999f-3873b10e3db1
            message: Maximum acknowledgement time must be in the range 1-30 sec.
    NotSupported:
      value:
        errors:
          - code: edge.notsupported
            message: Not supported.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    invalid-auth-header:
      value:
        errors:
          - code: edge.auth.invalidToken
            status: 401
            title: Token is invalid.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    missing-auth-header:
      value:
        errors:
          - code: edge.auth.missingToken
            status: 401
            title: Token is required.
            correlationId: 3505f6bd-30cd-4deb-981d-02e89f82aa8f
    expired-auth-header:
      value:
        errors:
          - code: edge.auth.expiredToken
            status: 401
            title: Token is expired.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    something-went-wrong:
      value:
        errors:
          - code: edge.internalServerError
            status: 500
            title: The server encountered an unknown error.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-request-body:
      value:
        errors:
          - code: edge.job.invalidRequestBody
            status: 400
            title: Invalid request body.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    invalid-hostname:
      value:
        errors:
          - code: edge.invalidHostName
            status: 400
            title: "Invalid hostname: must be dot-separated, contain no spaces, begin and end with an alphanumeric character, and avoid consecutive dots or invalid characters."
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-hostname-length-exceeds-limit:
      value:
        errors:
          - code: edge.hostNameLengthExceeds
            status: 400
            title: Hostname length exceeds the limit of 64 characters.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-hostname-length-below-limit:
      value:
        errors:
          - code: edge.hostNameLengthBelowMinimum
            status: 400
            title: Hostname length is below the minimum limit of 1 character.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    user-not-permitted:
      value:
        errors:
          - code: edge.notPermitted
            status: 401
            title: Access denied.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    unable-to-verify-auth-header:
      value:
        errors:
          - code: auth.token.unableToVerifyToken
            status: 401
            title: Unable to verify token.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    service-not-running:
      value:
        errors:
          - code: edge.SystemServiceNotRunning
            status: 503
            title: System service is not running on the host.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    forbidden-auth-error:
      value:
        errors:
          - code: edge.auth.forbidden
            status: 403
            title: User does not have permission to update hostname.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    query-parameter-invalid-error:
      value:
        errors:
          - code: edge.check.invalidDetailedQueryParam
            status: 400
            title: Invalid query parameter.
            message: Invalid query parameter. Only 'detailed' is supported with value 'true' or 'false'.
            correlationId: 123e4567-e89b-12d3-a456-426614174000
    edge-device-not-onboarded-error:
      value:
        errors:
          - code: edge.notActivated
            status: 400
            title: Edge device is not onboarded.
            message: Edge device is not onboarded. Please onboard the device before performing this operation.
            correlationId: 123e4567-e89b-12d3-a456-426614174000
    forbidden-auth-error_for-update-system-notification:
      value:
        errors:
          - code: edge.auth.forbidden
            status: 403
            title: User does not have permission to update system notification.
            message: User does not have permission to update system notification..Please log in with an admin account.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
    invalid-system-message-length-exceeds-limit:
      value:
        errors:
          - code: edge.systemNotification.lengthExceeded
            status: 400
            title: System notification message length exceeds the limit of 300 characters..
            message: The system notification message exceeds the maximum allowed length of 300 characters. Please provide a shorter message.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-system-notification:
      value:
        errors:
          - code: edge.systemNotification.invalid
            status: 400
            title: "Unable to update system notification only letters,numbers,spaces,and the characters . - _ : are allowed."
            message: "The system notification message contains unsupported characters. Only letters, numbers, spaces, and the characters . - _ : are allowed."
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-system-notification-request-body:
      value:
        errors:
          - code: edge.systemNotification.invalidRequestBody
            status: 400
            title: Unable to update system notification due to invalid request body or empty body.
            message: Unable to update system notification due to invalid request body.Please ensure the request body is correctly formatted and contains the required fields.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    unable-to-parse-request-body:
      value:
        errors:
          - code: edge.unableToParseBodyData
            status: 400
            title: Invalid request body provided.
            message: Unable to update system notification due to invalid request body.Please ensure the request body is correctly formatted and contains the required fields.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-system-notification-message-required:
      value:
        errors:
          - code: edge.systemNotification.message.required
            status: 400
            title: "Unable to update system notification: message is required."
            message: "Unable to update system notification: message is required.Please provide a message to update the system notification."
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    invalid-system-notification-no-change:
      value:
        errors:
          - code: edge.systemNotification.noChange
            status: 400
            title: "No changes detected in system notification configuration"
            message: "No changes detected in system notification configuration. Please ensure that the new message is different from the current one before attempting to update."
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    dnsReachabilitySimpleExample:
      summary: Simple response example
      value:
        dnsReachability:
          status: "OK"
          results:
            dnsServerResponsive:
              status: 1
              details:
                - server: "8.8.8.8"
                  response: "responded successfully test dns query in 28.000000 ms"
            domainResolution:
              status: 1
              details:
                - domain: "siemens.com"
                  dnsServer: "8.8.8.8"
                  status: "OK"
            reachDomainAddress:
              status: 1
              details:
                - domain: "siemens.com"
                  status: "OK"
    dnsReachabilityDetailedExample:
      summary: Detailed response example
      value:
        dnsReachability:
          status: "OK"
          results:
            dnsServerResponsive:
              status: 1
              details:
                - server: "8.8.8.8"
                  response: "responded successfully test dns query in 28.000000 ms"
            domainResolution:
              status: 1
              details:
                - domain: "siemens.com"
                  dnsServer: "8.8.8.8"
                  status: "OK"
                  dnsResolutionInfo: "Domain 'siemens.com' resolved using server '8.8.8.8' in 259.000000 milliseconds."
                  resolvedIps:
                    - "192.0.2.1"
            reachDomainAddress:
              status: 1
              details:
                - domain: "siemens.com"
                  status: "OK"
                  ipChecks:
                    - ipAddress: "192.0.2.1"
                      response: "domain siemens.com address 13.248.167.215:443 latency 2.000000 millisecond reached successfully"

    deviceinfodetailed:
      summary: device info detailed data
      value:
        deviceId: d796e233cf794b028ec945efce00f24d
        deviceName: myEdgeDevice
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            l2IPv4: 192.168.182.0
            l2SubnetMask: 255.255.254.0
            l2Gateway: 192.168.182.1
            macAddress: 00:0C:29:83:54:A5
        manufacturerName: Siemens
        serialNumber: S159765215
        productId: 6ES7647-8BD31-0CW1
        firmwareVersion: simatic-ipc-ied-os-v3.0.0-51
        productName: SIMATIC IPC227G
        biosVersion: S5C620.86B.01.01.0016.082920171234

    deviceInfoBeforeOnboardingWithLayer-2:
      summary: device info with enabled layer-2 before onboarding of device
      value:
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            l2IPv4: 192.168.182.0
            l2SubnetMask: 255.255.254.0
            l2Gateway: 192.168.182.1
            macAddress: 00:0C:29:83:54:A5
        manufacturerName: Siemens
        serialNumber: S159765215
        productId: 6ES7647-8BD31-0CW1
        firmwareVersion: simatic-ipc-ied-os-v3.0.0-51
        productName: SIMATIC IPC227G
        biosVersion: S5C620.86B.01.01.0016.082920171234

    deviceInfoAfterOnboardingWithoutLayer-2:
      summary: device info with disabled layer-2 after onboarding of device
      value:
        deviceId: d796e233cf794b028ec945efce00f24d
        deviceName: myEdgeDevice
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            macAddress: 00:0C:29:83:54:A5
        manufacturerName: Siemens
        serialNumber: S159765215
        productId: 6ES7647-8BD31-0CW1
        firmwareVersion: simatic-ipc-ied-os-v3.0.0-51
        productName: SIMATIC IPC227G
        biosVersion: S5C620.86B.01.01.0016.082920171234

    deviceInfoBeforeOnboardingWithoutLayer-2:
      summary: device info without layer-2 before onboarding of device
      value:
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            macAddress: 00:0C:29:83:54:A5
        manufacturerName: Siemens
        serialNumber: S159765215
        productId: 6ES7647-8BD31-0CW1
        firmwareVersion: simatic-ipc-ied-os-v3.0.0-51
        productName: SIMATIC IPC227G
        biosVersion: S5C620.86B.01.01.0016.082920171234

    deviceInfoAfterOnboardingWithoutSystemInfoFile:
      summary: device info without  /etc/system-info file after onboarding of device
      value:
        deviceId: d796e233cf794b028ec945efce00f24d
        deviceName: myEdgeDevice
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            l2IPv4: 192.168.182.0
            l2SubnetMask: 255.255.254.0
            l2Gateway: 192.168.182.1
            macAddress: 00:0C:29:83:54:A5

    deviceInfoBeforeOnboardingWithoutSystemInfoFile:
      summary: device info without /etc/system-info before onboarding of device
      value:
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            l2IPv4: 192.168.182.0
            l2SubnetMask: 255.255.254.0
            l2Gateway: 192.168.182.1
            macAddress: 00:0C:29:83:54:A5

    deviceInfoAfterOnboardingWithLayer-2:
      summary: device info with Layer-2 after onboarding of device
      value:
        deviceId: d796e233cf794b028ec945efce00f24d
        deviceName: myEdgeDevice
        networks:
          - interfaceName: ens33
            ipAddress: 192.19.182.155
            subnetMask: 255.255.255.0
            gateway: 192.19.182.155
            l2IPv4: 192.168.182.0
            l2SubnetMask: 255.255.254.0
            l2Gateway: 192.168.182.1
            macAddress: 00:0C:29:83:54:A5
        manufacturerName: Siemens
        serialNumber: S159765215
        productId: 6ES7647-8BD31-0CW1
        firmwareVersion: simatic-ipc-ied-os-v3.0.0-51
        productName: SIMATIC IPC227G
        biosVersion: S5C620.86B.01.01.0016.082920171234

    iemReachabilitySimpleExample:
      summary: Simple response example
      value:
        iemReachability:
          status: "OK"
          results:
            proxyServerResponsive:
              status: 1
              details:
                - server: "de.siemens.com"
                  response: "connected successfully to proxy server in 28.000000 ms"
            serverEndPointResponsive:
              status: 1
              details:
                - server: "192.168.20.105"
                  response: "connected successfully to endpoint server in 28.000000 ms"
    iemReachabilityDetailedExample:
      summary: Detailed response example
      value:
        iemReachability:
          status: "OK"
          results:
            proxyServerResponsive:
              status: 1
              details:
                - server: "de.siemens.com"
                  response: "connected successfully to proxy server in 28.000000 ms"
                  attemptCount: 1
                  attempts:
                    - destIp: "10.218.201.81"
                      id: 1
                      statusCode: 200
                      connectionInfo:
                        transferredData: "0.146484 kb"
                        latency: "146.484 ms"
                      certInfo:
                        - issuer: "CN=DigiCert Global G2 TLS RSA SHA256 2020 CA1,O=DigiCert Inc,C=US"
                          cn: "DigiCert Global G2 TLS RSA SHA256 2020 CA1"
                          san: "[code.siemens.com]"
                          validity: "Valid from 2025-03-27 00:00:00 +0000 UTC to 2026-03-26 23:59:59 +0000 UTC"
            serverEndPointResponsive:
              status: 1
              details:
                - server: "192.168.22.105"
                  response: "connected successfully to proxy server in 28.000000 ms"
                  attemptCount: 1
                  attempts:
                    - destIp: "10.218.201.81"
                      id: 1
                      statusCode: 200
                      connectionInfo:
                        transferredData: "0.146484 kb"
                        latency: "146.484 ms"
                      certInfo:
                        - issuer: "CN=DigiCert Global G2 TLS RSA SHA256 2020 CA1,O=DigiCert Inc,C=US"
                          cn: "DigiCert Global G2 TLS RSA SHA256 2020 CA1"
                          san: "[code.siemens.com]"
                          validity: "Valid from 2025-03-27 00:00:00 +0000 UTC to 2026-03-26 23:59:59 +0000 UTC"
    iemReachabilityFailedDetailedExample:
      summary: IEM reachability failed detailed response example
      value:
        iemReachability:
          status: "FAILED"
          results:
            proxyServerResponsive:
              status: 0
              details:
                - server: "de.siemens.com"
                  response: "failed to connect to proxy server"
                  attemptCount: 1
                  attempts:
                    - destIp: "10.218.201.81"
                      id: 1
                      connectionInfo:
                        latency: "146.484 ms"
                      error: 'Connect "https://de.siemens.com/": Proxy Authentication Required'
            serverEndPointResponsive:
              status: 0
              details:
                - server: "192.168.22.105"
                  response: "connected successfully to proxy server in 28.000000 ms"
                  attemptCount: 1
                  attempts:
                    - destIp: "10.218.201.81"
                      id: 1
                      connectionInfo:
                        latency: "146.484 ms"
                      error: 'failed to connect to endpoint: Get "https://192.168.22.105/": Proxy Authentication Required'
    iemReachabilityFailedSimpleExample:
      summary: IEM reachability failed simple response example
      value:
        iemReachability:
          status: "FAILED"
          results:
            proxyServerResponsive:
              status: 0
              details:
                - server: "de.siemens.com"
                  response: "failed to connect to proxy server"
            serverEndPointResponsive:
              status: 0
              details:
                - server: "192.168.20.105"
                  response: "failed to connect to endpoint: https://192.168.20.105/"
    tcpDiagnoseRequestExample:
      summary: Request for TCP Diagnose with multiple targets
      value:
        targets:
          - host: "192.168.1.11"
            port: 502
          - host: "mqtt.factory.local"
            port: 1883
          - host: "timeseries-db.company.com"
            port: 5432
    tcpDiagnoseSimpleExample:
      summary: Simple TCP Diagnose response example
      value:
        tcpReachability:
          status: "OK"
          executionError: ""
          results:
            tcpConnection:
              status: 1
              details:
                - host: "mqtt.eclipseprojects.io"
                  port: 1883
                  status: "OK"
                - host: "opcua.server.com"
                  port: 4840
                  status: "OK"

    tcpDiagnoseDetailedExample:
      summary: Detailed TCP Diagnose response example
      value:
        tcpReachability:
          status: "OK"
          executionError: ""
          results:
            tcpConnection:
              status: 1
              details:
                - host: "mqtt.eclipseprojects.io"
                  port: 1883
                  status: "OK"
                  response: "Successfully connected to mqtt.eclipseprojects.io:1883 in 150.000 ms"
                  latency: 150
                - host: "opcua.server.com"
                  port: 4840
                  status: "OK"
                  response: "Successfully connected to opcua.server.com:4840 in 280.000 ms"
                  latency: 280

    tcpDiagnoseDetailedWithErrorExample:
      summary: Detailed TCP Diagnose response example with mixed success and failure
      value:
        tcpReachability:
          status: "FAILED"
          executionError: ""
          results:
            tcpConnection:
              status: 0
              details:
                - host: "mqtt.eclipseprojects.io"
                  port: 1883
                  status: "OK"
                  response: "Successfully connected to mqtt.eclipseprojects.io:1883 in 150.000 ms"
                  latency: 150
                - host: "test.opcua.server.com"
                  port: 4840
                  status: "FAILED"
                  error: "Failed to connect to test.opcua.server.com:4840. Error: dial tcp: lookup test.opcua.server.com: no such host"
                  errorCategory: "DNS"

    tcpDiagnoseSimpleWithErrorExample:
      summary: Simple TCP Diagnose response example with mixed success and failure
      value:
        tcpReachability:
          status: "FAILED"
          executionError: ""
          results:
            tcpConnection:
              status: 0
              details:
                - host: "mqtt.eclipseprojects.io"
                  port: 1883
                  status: "OK"
                - host: "test.opcua.server.com"
                  port: 4840
                  status: "FAILED"
                  errorCategory: "DNS"

    tcpDiagnoseDetailedWithPartialSuccessExample:
      summary: Detailed TCP Diagnose response example with partial success and failure
      value:
        tcpReachability:
          status: "FAILED"
          executionError: ""
          results:
            tcpConnection:
              status: 0
              details:
                - host: "mqtt.eclipseprojects.io"
                  port: 1883
                  status: "OK"
                  response: "Successfully connected to mqtt.eclipseprojects.io:1883 in 150.000 ms"
                  latency: 150
                - host: "test.opcua.server.com"
                  port: 4840
                  status: "FAILED"
                  error: "Connection attempt skipped for test.opcua.server.com:4840: deadline exceeded"
                  errorCategory: "DeadlineExceeded"

    tcpDiagnoseSimpleWithPartialSuccessExample:
      summary: Simple TCP Diagnose response example with partial success and failure
      value:
        tcpReachability:
          status: "FAILED"
          executionError: ""
          results:
            tcpConnection:
              status: 0
              details:
                - host: "opcua.server.com"
                  port: 4840
                  status: "OK"
                - host: "test.opcua.server.com"
                  port: 502
                  status: "FAILED"
                  errorCategory: "DeadlineExceeded"
    emptyTarget:
      value:
        errors:
          - code: edge.tcpDiagnose.emptyTarget
            status: 400
            title: No Targets Provided.
            message: The targets array in the request body must not be empty. Please specify at least one host and port.
            correlationId: 123e4567-e89b-12d3-a456-426614174000
    invalidTcpTargetsQueryParam:
      value:
        errors:
          - code: edge.tcpDiagnose.invalidDetailedQueryParam
            status: 400
            title: Invalid query parameter.
            message: Invalid query parameter. Only 'detailed' is supported with value 'true' or 'false'.
            correlationId: 123e4567-e89b-12d3-a456-426614174000
    invalidTcpTargetsRequestBody:
      summary: response for an invalid TCP targets request body
      value:
        errors:
          - code: edge.tcpDiagnose.invalidRequestBody
            status: 400
            title: Invalid TCP Diagnose Request Body
            message: The request body for TCP diagnose contains missing or empty target information. Ensure 'targets' is an array of objects, each with valid 'host' (string) and 'port' (integer) properties.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    unableToParseTcpTargetsRequestBody:
      summary: response when the request body JSON is malformed or unparseable
      value:
        errors:
          - code: edge.tcpDiagnose.unableToParseBodyData
            status: 400
            title: Unable to parse request body for TCP Diagnose
            message: The request body provided for TCP diagnose could not be parsed. Please ensure it is valid JSON.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    tcpDiagnoseTooManyTargets:
      summary: response when the number of targets exceeds the maximum allowed
      value:
        errors:
          - code: edge.tcpDiagnose.tooManyTargets
            status: 400
            title: Too Many Targets
            message: The request contains too many TCP diagnose targets. A maximum of 10 targets are allowed per request.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1

    tcpDiagnoseInvalidPortRange:
      summary: response when a target's port is outside the valid range
      value:
        errors:
          - code: edge.tcpDiagnose.invalidPortRange
            status: 400
            title: Invalid Port Number
            message: One or more target ports are outside the valid range of 1 to 65535. Please check the port numbers.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1

    tcpDiagnoseInvalidIpAddress:
      summary: response when a target's host is not a valid IP address format
      value:
        errors:
          - code: edge.tcpDiagnose.invalidIpAddress
            status: 400
            title: Invalid IP Address Format
            message: One or more target hosts provided are not in a valid IPv4 address format.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1

    tcpDiagnoseIpv6NotSupported:
      summary: response when an IPv6 address is provided as a target host
      value:
        errors:
          - code: edge.tcpDiagnose.ipv6NotSupported
            status: 400
            title: IPv6 Addresses Not Supported
            message: One or more target hosts are IPv6 addresses, which are currently not supported for TCP diagnose. Please use IPv4 addresses.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1

    tcpDiagnoseInvalidHost:
      summary: response when a target's host is neither a valid IP nor a resolvable hostname
      value:
        errors:
          - code: edge.tcpDiagnose.invalidHost
            status: 400
            title: Invalid Hostname
            message: One or more target hosts are invalid. Please ensure they are valid or resolvable hostnames.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    tcpDiagnoseNotaAllowed:
      summary: response when a target's host is 'localhost' or '127.0.0,.1'
      value:
        errors:
          - code: edge.tcpDiagnose.notAllowed
            status: 400
            title: TCP check not allowed for Localhost or Loopback targets.
            message: TCP connectivity checks cannot be performed on localhost or loopback targets, including IPv4 (127.x.x.x) addresses.
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
    tooManyRequests:
      value:
        errors:
          - code: edge.check.tooManyRequests
            status: 429
            title: Too Many Requests
            message: The client has sent too many requests in a given amount of time. Please try again later.
            correlationId: 123e4567-e89b-12d3-a456-426614174000
    NetworkInterfaceNotFound:
      value:
        errors:
          - code: edge.networks.interfaceNotFound
            title: Network interface not found.
            message: No network interface matched the requested interfacename.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
            status: 404
    NetworkInterfaceTypeNotSupported:
      value:
        errors:
          - code: edge.networks.interfaceTypeNotSupported
            message: Network status monitoring is not supported for this type of interface.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
            title: Network Interface Type Not Supported
            status: 400
    CellularNotCapableError:
      value:
        errors:
          - code: edge.cellular.notCapable
            correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
            message: "The device does not have cellular capabilities. Please check the device specifications and ensure that it supports cellular connectivity."
            title: Device Not Capable for Cellular Connectivity
            status: 400
    NetworkServiceNotRunning:
      value:
        errors:
          - code: edge.NetworkServiceNotRunning
            message: Network service is not running on the host.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    NetworkServiceNotRunningDetailed:
      value:
        errors:
          - code: edge.NetworkServiceNotRunning
            title: Network Service Not Running
            message: Network service is not running on the host.
            correlationId: 5432e1d8-5916-4619-88ec-a507f83331bd
            status: 503
    too-many-requests-error:
      value:
        errors:
          - code: edge.request.tooManyRequests
            status: 429
            title: Too Many Requests
            message: The client has sent too many requests in a given amount of time. Please try again later.
            correlationId: 123e4567-e89b-12d3-a456-426614174000
  responses:
    TokenError:
      description: |-
        Unauthorized:
        - Missing the auth token
        - Invalid auth token
        - Expired auth token
        - User of the auth token was not found
        - Unable to verify auth token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            ExampleExpiredTokenError:
              $ref: "#/components/examples/ExpiredToken"
            ExampleInvalidTokenError:
              $ref: "#/components/examples/InvalidToken"
            ExampleMissingTokenError:
              $ref: "#/components/examples/MissingToken"
            ExampleTokenUserNotFoundError:
              $ref: "#/components/examples/TokenUserNotFound"
            ExampleUnableToVerifyTokenError:
              $ref: "#/components/examples/UnableToVerifyToken"
  securitySchemes:
    API_Key_1:
      name: Authorization
      type: apiKey
      in: header
