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://localhost/device/edge/api/v2
tags:
  - name: device
  - name: login
  - name: notifications
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
            - 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
          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.
        '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
          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.unableToAddCertiificates
                        logref: c105072b-39cb-49d9-999f-3873b10e3db1
                        message: Unable to add trust certificates.
        '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:
                ExampleExpirdTokenError:
                  $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 apperas 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'
  /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'
              examples:
                example-1:
                  value:
                    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
        '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: []
  /info:
    get:
      summary: Get Device identifynformation data
      tags:
        - device
      responses:
        '200':
          description: Returns Device information in form of object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceInfo'
        '401':
          description: |-
            Returns Unauthorized errors -

            - Expired auth token
            - Invalid auth token
            - Auth token user not found
            - Unable to verify auth token
            - Missing 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'
                NotPermitted:
                  $ref: '#/components/examples/NotPermitted'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
      operationId: get-info
      description: |-
        This method returns Device information of Industrial Edge Device like:

          1. deviceId information
           
          2. deviceName information
           
          3. networks information
          - interfaceName
          - ipAddress
          - subnetMask
          - gateway
          - macAddress
          - l2Ipv4
          - l2SubnetMask
          - l2Gateway

          4. firmwareVersion information
      parameters:
        - $ref: '#/components/parameters/Authorization'
      security:
        - API Key - 1: []
  /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: []
  /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:
                  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
        '401':
          description: Unauthorized

          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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/ErrorResponse'
              examples:
                something-went-wrong:
                  $ref: '#/components/examples/something-went-wrong'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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
              x-examples:
                example-1:
                  name: value
              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: []
components:
  schemas:
    Login:
      type: object
      properties:
        username:
          type: string
          description: Associated user name for basic auth
        password:
          type: string
          description: Associated password for basic auth
        verificationCode:
          type: string
      required:
        - username
        - password
    HostName:
      type: object
      title: HostName
      properties:
        hostname:
          type: string
          description: The hostname of the IE Runtime device
      required:
        - hostname
    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 distincly 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
      x-examples:
        example-1:
          code: string
          logref: c105072b-39cb-49d9-999f-3873b10e3db1
          message: string
    Error-response:
      title: Error
      type: object
      description: 'Error consist of code which is associated with message and logref which is a uuid, used to distincly identify the error.'
      x-examples:
        example-1:
          code: string
          status: integer
          title: string
          correlationId: c105072b-39cb-49d9-999f-3873b10e3db1
      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
    ErrorResponse:
      title: ErrorResponse
      description: An array of the error model, hence allowing response on sigle as well as multiple errors
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      x-examples:
        example-1:
          errors:
            - code: string
              logref: c105072b-39cb-49d9-999f-3873b10e3db1
              message: string
    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
      x-examples:
        example-1:
          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.
                    The request must include a valid authorization token in the header.'
      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
        firmwareVersion: 1.11.1
      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  
        firmwareVersion:
          type: string
          description: Firmware 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.
  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
  examples:
    ExpiredToken:
      value:
        errors:
          - code: edge.auth.expiredToken
            message: Token expired.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    InvalidToken:
      value:
        errors:
          - code: edge.auth.invalidToken
            message: Token is invalid.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    TokenUserNotFound:
      value:
        errors:
          - code: auth.application.userNotFound
            message: User not found.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    UnableToVerifyToken:
      value:
        errors:
          - code: auth.token.unableToVerifyToken
            message: Unable to verify token.
            logref: 5432e1d8-5916-4619-88ec-a507f83331bd
    MissingToken:
      value:
        errors:
          - code: edge.auth.missingToken
            message: Token is required.
            logref: 3505f6bd-30cd-4deb-981d-02e89f82aa8f
    NotPermitted:
      value:
        errors:
          - code: edge.notPermitted
            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.
    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
    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
  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