openapi: 3.0.3

info:
  description: APIs Published by Siemens for SITRANS HUB IQ
  version: "0.0.1"
  title: SITRANS Hub IQ API's
  contact:
    name: Hub IQ API Support Team

servers:
  - description: SITRANS HUB IQ API - Production
    url: https://api.hubiq.siemens.com/hubiqapi/
  - description: SITRANS HUB IQ API - Staging
    url: https://{Route_53_DNS}/hubiqapi/

tags:
  - name: Company
    description: API's related to CURD operation on company
  - name: Device
    description: API's related to CURD operation on devices
  - name: Targets
    description: API's related to device data targets
  # - name: FOTA
  #   description: API's related to FOTA
  - name: ProcessValues
    description: API's related to flow mesurement data
  - name: Alarms
    description: API's related to alarm monitoring data
  - name: Parameters
    description: API's related to device parameter data
  - name: Notifications
    description: API's related to alarm subscriptions
  - name: Export
    description: Export API's to bulk export data in CSV format   


paths:

# Company APIs

  /company:
    post:
      operationId: CreateCompany
      tags:
        - Company
      security:
        - bearerAuth: []
      summary: Create a new child company
      description: >
        Let's admin create a new child company.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/CreateCompanyRequest"
      responses:
        "200":
          description: Successfully created a company
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/CreateCompanyResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"

  /companies/{company_id}:
    get:
      operationId: GetCompanyDetails
      tags:
        - Company
      security:
        - bearerAuth: []
      summary: Fetch Company and its child companies
      description: >
        Lets admin visualize the metadata of the company and the children companies.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
        - name: subchild
          in: query
          required: false
          schema:
            type: string
            default: True
            example: True
            enum:
              - True
              - False
            description: "If False is passed then same level will be returned, and if True is passed or this parameter is not passed then the whole hierarchy will be returned"
      responses:
        "200":
          description: Successfully retrieved the list of companies
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/ListCompaniesResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "403":
          $ref: "#/components/responses/403Error"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"

    delete:
      operationId: DeleteCompany
      tags:
        - Company
      security:
        - bearerAuth: []
      summary: Delete a company
      description: >
        Only the company administrator has the authority to remove its subsidiary companies. Self-deletion is restricted, and deleting companies with subsidiaries is also prohibited.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: The id of attached to the company, maximum size 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      responses:
        "200":
          description: Successfully deleted the company
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeleteCompanyResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "403":
          $ref: "#/components/responses/403Error"
        "405":
          $ref: "#/components/responses/405Error"
        "404":
          $ref: "#/components/responses/404Error"

    put:
        operationId: UpdateCompanyName
        tags:
          - Company
        security:
          - bearerAuth: []
        summary: Update Company Name
        description: >
          Lets operator to update company name.
        parameters:
          - in: header
            name: api-version
            required: true
            schema:
              type: string
              enum: ["1.0.0"]
              example: "1.0.0"
          - in: header
            name: auth-header
            required: true
            schema:
              type: string
              description: JWT Token
          - name: company_id
            in: path
            required: true
            description: The id of the company, maximum length 64 char.
            schema:
              type: string
              minimum: 1
              maximum: 64
        requestBody:
          required: true
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/UpdateCompanyRequest"

        responses:
          "200":
            description: Successfully updated company name
            content:
              application/json (Version 1.0.0):
                schema:
                  $ref: "#/components/schemas/UpdateCompanyResponse"
          "400":
            $ref: "#/components/responses/400Error"
          "403":
            $ref: "#/components/responses/403Error"
          "404":
            $ref: "#/components/responses/404Error"
          "500":
            $ref: "#/components/responses/500Error"

# Device APIs

  /companies/{company_id}/devices:
    post:
      tags:
        - Device
      security:
        - bearerAuth: []
      summary: Claim a device
      description: Lets user claim their devices under their company.
      operationId: RegisterDevices
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: This specifies the company id to which device will be registered, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/DeviceClaimRequest"
      responses:
        "200":
          description: Device is claimed successfully
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeviceClaimResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"

  /companies/{company_id}/devices/list:
    post:
      operationId: ListDevices
      tags:
        - Device
      security:
        - bearerAuth: []
      summary: Fetch All Devices
      description: >
        This API will return Devices claimed under given Company.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: The id of the company attached to the user, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/GetDevicesRequest"
      responses:
        "200":
          description: Successfully fetched the Devices list
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/GetDevicesResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"
        "400":
          $ref: "#/components/responses/400Error"

  /companies/{company_id}/devices/{device_id}:
    get:
      operationId: GetDeviceDetails
      tags:
        - Device
      security:
        - bearerAuth: []
      summary: Fetch a Device
      description: >
        This API will return device detail created under this company
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: The id of the company attached to the user, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
        - name: device_id
          in: path
          required: true
          description: The device_id of the to be fetched, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
      responses:
        "200":
          description: device under company is fetched successfully
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/GetOneDeviceResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"

    delete:
      operationId: DeleteDevice
      tags:
        - Device
      security:
        - bearerAuth: []
      summary: Delete a Device
      description: >
        This API will return device detail created under this company
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: The id of the company attached to the user, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
        - name: device_id
          in: path
          required: true
          description: The device_id of the to be deleted, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
      responses:
        "200":
          description: Device is successfully deleted
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeleteDeviceResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"

    put:
        operationId: UpdateDeviceLocation
        tags:
          - Device
        security:
          - bearerAuth: []
        summary: Update Device Location
        description: >
          Lets operator to update device location.
        parameters:
          - in: header
            name: api-version
            required: true
            schema:
              type: string
              enum: ["1.0.0"]
              example: "1.0.0"
          - in: header
            name: auth-header
            required: true
            schema:
              type: string
              description: JWT Token
          - name: company_id
            in: path
            required: true
            description: The id of the company, maximum length 64 char.
            schema:
              type: string
              minimum: 1
              maximum: 64
          - name: device_id
            in: path
            required: true
            description: The id of the device, maximum length 64 char.
            schema:
              type: string
              minimum: 1
              maximum: 64
        requestBody:
          required: true
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/UpdateDeviceRequest"

        responses:
          "200":
            description: Successfully updated company name
            content:
              application/json (Version 1.0.0):
                schema:
                  $ref: "#/components/schemas/UpdateDeviceResponse"
          "400":
            $ref: "#/components/responses/400Error"
          "403":
            $ref: "#/components/responses/403Error"
          "404":
            $ref: "#/components/responses/404Error"
          "500":
            $ref: "#/components/responses/500Error"


  /companies/{company_id}/devices/kpis:
    get:
      operationId: GetDeviceKPI
      tags:
        - Device
      security:
        - bearerAuth: []
      summary: Fetch Device KPIs
      description: >
        This API will return total, online and offline device count for the selected company
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: The id of the company attached to the user, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64

      responses:
        "200":
          description: device count under company is fetched successfully
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeviceKPIResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"

  /companies/{company_id}/devices/move:
    post:
      tags:
        - Device
      security:
        - bearerAuth: []
      summary: Move a list of devices
      description: Lets user to move their devices from one company to another.
      operationId: MoveDevices
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: This specifies the company id to which device will be registered, maximum size is 64 char.
          schema:
            type: string
            maximum: 64
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/MoveDevicesRequest"
      responses:
        "200":
          description: Device is moved successfully
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/MoveDevicesResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"

# # FOTA API's
#   /companies/{company_id}/devices/firmwares/update:
#     post:
#       operationId: DeviceUpdateFirmware
#       tags:
#         - FOTA
#       security:
#         - bearerAuth: []
#       summary: Update Device Firmware
#       description: Update Latest firmware for one or more device. 
#       parameters:
#         - in: header
#           name: api-version
#           required: true
#           schema:
#             type: string
#             enum: ["1.0.0"]
#             example: "1.0.0"
#         - in: header
#           name: auth-header
#           required: true
#           schema:
#             type: string
#             description: JWT Token
#         - name: company_id
#           in: path
#           required: true
#           description: This specifies the company id to which device will be registered, maximum size is 64 char.
#           schema:
#             type: string
#             maximum: 64
#       requestBody:
#         required: true
#         content:
#           application/json (Version 1.0.0):
#             schema:
#               $ref: "#/components/schemas/FirmwareUpdateRequest"
#       responses:
#         '202':
#           description: Accepted and in progress (whatever records are successfully accepted are is progress)
#           content:
#             application/json (Version 1.0.0):
#               schema:
#                 $ref: '#/components/schemas/FirmwareUpdateResponse'
#         "400":
#           $ref: "#/components/responses/400Error"
#         "403":
#           $ref: "#/components/responses/403Error"
#         "401":
#           $ref: "#/components/responses/401Error"
#         "404":
#           $ref: "#/components/responses/405Error"
#         "500":
#           $ref: "#/components/responses/500Error"


# Telemetry Data API's

  /companies/{company_id}/devices/{device_id}/process-values:
    get:
      operationId: GetFlowMeasurementData
      description: >
        This API will return process values data of a specific device & parameters for a given duration.
      tags:
        - ProcessValues
      security:
        - bearerAuth: []
      summary: Get Process Values of a device
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: "This is company id linked to the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
        - name: device_id
          in: path
          required: true
          description: "This is Device ID of the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
        - name: from_date_time
          in: query
          required: true
          schema:
            type: string
            example: "YYYY-MM-DDThh:mm:ss.SSSZ"
            default: None
            description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"
        - name: to_date_time
          in: query
          required: true
          schema:
            type: string
            example: "YYYY-MM-DDThh:mm:ss.SSSZ"
            default: None
            description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"
        - name: next_token
          in: query
          schema:
            type: string
            default: None
            example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
            description: "A base64 encoded string to fetch the next page of the paginated result."
        - name: parameters
          in: query
          required: true
          schema:
            type: string
            default: None
            example: "totalizer1,remainingbattery,totalizer2"
            description: "comma separated list of parameters to be fetched. One value must be passed"
      responses:
        "200":
          description: Successfully fetched list of all measurement values.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/GetMeasurementDataResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "403":
          $ref: "#/components/responses/403Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"


  /companies/{company_id}/devices/{device_id}/process-values/latest:
    get:
      operationId: GetLatestFlowMeasurementData
      description: >
        This API will return only the latest process values of a specific device.
      tags:
        - ProcessValues
      security:
        - bearerAuth: []
      summary: Get Latest Process Values of a device
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: "This is company id linked to the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
        - name: device_id
          in: path
          required: true
          description: "This is Device ID of the device, maximum size is 64 char."
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
      responses:
        "200":
          description: "Successfully fetched the latest process value."
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/GetLatestMeasurementDataResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "403":
          $ref: "#/components/responses/403Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"


# Fetch Device Alarm APIs

  /companies/{company_id}/devices/{device_id}/alarms:
    get:
      operationId: GetDeviceAlarmsData
      tags:
        - Alarms
      security:
        - bearerAuth: []
      summary: Get Alarms for a device
      description: >
        This API returns the list of alarms raised for a device.
        <br><br>
        note: next_token and previous_token both must not be present in the same request
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: "The company id which is linked to the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
        - name: device_id
          in: path
          required: true
          description: "The device id to fetch the alarms from, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
        - name: from_date_time
          in: query
          schema:
            type: string
            example: "YYYY-MM-DDThh:mm:ss.SSSZ"
            default: None
            description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"
        - name: to_date_time
          in: query
          schema:
            type: string
            example: "YYYY-MM-DDThh:mm:ss.SSSZ"
            default: None
            description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"
        - name: page_size
          in: query
          schema:
            type: integer
            example: 15
            default: 15
            enum:
              - 15
              - 30
              - 50
            description: "Optional. The maximum of values to fetch in a request. Will add a 'NextToken' key to fetch the next page. Defaults to 15"
        - name: currently_active
          in: query
          schema:
            type: string
            example: True
            default: false
            enum:
              - True
              - False
            description: Pass true if need to fetch currently active alarms
        - name: next_token
          in: query
          schema:
            type: string
            default: None
            example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
            description: "A base64 encoded string to fetch the next page of the paginated result."
        - name: previous_token
          in: query
          schema:
            type: string
            default: None
            example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
            description: "A base64 encoded string to fetch the previous page of the paginated result."
      responses:
        "200":
          description: Successfully fetched List of alarms data.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/GetDeviceAlarmsResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "403":
          $ref: "#/components/responses/403Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"


  # Alarm Metadata APIs

  # /alarm-metadata:
  #   post:
  #     operationId: CreateAlarmMetadata
  #     tags:
  #       - Alarms
  #     security:
  #       - bearerAuth: []
  #     summary: Create Alarm Metadata
  #     description: Create a new alarm metadata entry.
  #     parameters:
  #       - in: header
  #         name: api-version
  #         required: true
  #         schema:
  #           type: string
  #           enum: ["1.0.0"]
  #           example: "1.0.0"
  #       - in: header
  #         name: auth-header
  #         required: true
  #         schema:
  #           type: string
  #           description: JWT Token
  #     requestBody:
  #       required: true
  #       content:
  #         application/json:
  #           schema:
  #             $ref: "#/components/schemas/CreateAlarmMetadataRequest"
  #     responses:
  #       "201":
  #         description: Alarm metadata created successfully.
  #         content:
  #           application/json:
  #             schema:
  #               $ref: "#/components/schemas/CreateAlarmMetadataResponse"
  #       "400":
  #         $ref: "#/components/responses/400Error"
  #       "500":
  #         $ref: "#/components/responses/500Error"

  /alarms-metadata:
    get:
      operationId: GetAlarmMetadata
      tags:
        - Alarms
      security:
        - bearerAuth: []
      summary: Get Alarm Metadata
      description: Retrieve a list of alarm metadata entries.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token       
        - name: deviceType
          in: query
          description: Filter alarm metadata by device type.
          required: false
          schema:
            type: string
          example: "Mag8000-4G"
        - name: alarmName
          in: query
          description: Filter alarm metadata by alarm name.
          required: false
          schema:
            type: string
          example: "AL2"
      responses:
        "200":
          description: Alarm metadata retrieved successfully.
          content:
            application/json:
               schema:
                  $ref: "#/components/schemas/GetAlarmMetadataResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"

  /companies/{company_id}/export/devices:
    get:
      operationId: ExportDevice
      tags:
        - Export
      security:
        - bearerAuth: []    
      summary: Export Company Device Data to CSV
      description: Retrieves device data for a specified company ID and its child companies returns it as a downloadable CSV file.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token      
        - name: company_id
          in: path
          required: true
          description: The unique identifier of the company whose device data is to be exported.
          schema:
            type: string
            example: companyA
      responses:
        '200':
          description: A CSV file containing the requested company device data.
          content:
            text/csv:
              schema:
                type: string
                format: binary # Indicates that the response body is a file
              example: |
                acknowledgementStatus,claimedOn,claimedStatus,companyId,companyName,connectivityStatus,currentFirmwareVersion,deveui,deviceApplicationIdentifier,deviceId,deviceLocation,deviceType,iccid,imei,inAlarmState,inErrorState,isTargetMapped,lastConnectedOn,latitude,longitude,macAddress,mlfb,provisionedOn,rolledoutFirmwareStatus,rolledoutFirmwareVersion,serialNumber
                UNACKNOWLEDGED,2025-04-11 04:32:48,UNCLAIMED,d8b19256-1acd-4cd7-92e5-544377d3e4a5,SIWA,UNKNOWN,01.01.11,,,"1107482f-9d9c-45a6-843f-616a5e3a79d4","Electronic city, Bangalore, India",CC220,,,True,False,False,2025-04-06 08:58:32,-31.653612,108.522248,TESTMACID2,MLFB12,2025-04-07 08:58:22,rolled_out,02.09.00,
                UNACKNOWLEDGED,2025-06-19 17:49:39,CLAIMED,SIEMENS,SIEMENS,DISCONNECTED,01.00.07,,test_d,9400f1b5-8f58-4150-8dad-7612849bcb63,"Electronic city, Bangalore, India",Mag8000-4G,994055318614494230187,1234567778,False,False,False,2025-06-30 08:04:37,-58.753161,103.368565,,MLFB92,2025-04-07 08:58:31,,,"1234567778"
                UNACKNOWLEDGED,,UNCLAIMED,d8b19256-1acd-4cd7-92e5-544377d3e4a5,SIWA,UNKNOWN,01.01.01,,,"7fa63b29-eda5-4a6f-aeb0-0ba1248b128f","Electronic city, Bangalore, India",CC220,,,False,False,False,2025-04-06 08:58:32,-10.882747,81.478506,TESTMACID1,,2025-04-07 08:58:32,rolled_out,02.10.17,
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"


  /companies/{company_id}/devices/{device_id}/export/alarms:
    get:
      operationId: ExportAlarms
      tags:
        - Export
      security:
        - bearerAuth: []   
      summary: Export Device Alarm Data to CSV
      description: Retrieves alarm data for a specified device ID and returns it as a downloadable CSV file.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token      
        - name: device_id
          in: path
          required: true
          description: The unique identifier of the device whose alarm data is to be exported.
          schema:
            type: string
            example: c1141353-8cc2-40f4-94c3-46865e922946
        - name: company_id
          in: path
          required: true
          description: The unique identifier of the company whose device data is to be exported.
          schema:
            type: string
            example: companyA            
      responses:
        '200':
          description: A CSV file containing the requested device alarm data.
          content:
            text/csv:
              schema:
                type: string
                format: binary # Indicates that the response body is a file
              example: |
                alarm_number,collectedTimestamp,alarmId,alarmType,alarmStatus,alarmDescription
                AL06,2025-07-07 07:41:23,debaddc1-4d9d-428d-83e1-82017d11e922,ModuleAlarm,ACTIVE,Module reboot
                AL22,2025-07-07 07:41:23,69e560de-5846-4fa0-b081-f1e54163c146,HostDeviceAlarm,ACTIVE,Flow overload
                AL26,2025-07-07 07:41:23,64972e4e-a792-4b7e-809a-42317a380639,HostDeviceAlarm,ACTIVE,Leakage
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"

  /companies/{company_id}/export-file-configuration:
    get:
      operationId: FetchExportFileConfigurations
      tags:
        - Export
      security:
        - bearerAuth: []    
      summary: Fetch File Export Configuration
      description: Fetch the export file configuration for a specified company ID.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token      
        - name: company_id
          in: path
          required: true
          description: The unique identifier of the company whose device data is to be exported.
          schema:
            type: string
            example: companyA
      responses:
        '200':
          description: Successfully fetched export file configuration.
          content:
            application/json:
               schema:
                  $ref: "#/components/schemas/GetExportFileConfigurationResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"


    post:
      operationId: ExportFileConfigurations
      tags:
        - Export
      security:
        - bearerAuth: []    
      summary: Save Export File Configuration
      description: Save the export file configuration for a specified company ID.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token      
        - name: company_id
          in: path
          required: true
          description: The unique identifier of the company whose device data is to be exported.
          schema:
            type: string
            example: companyA
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/ExportFileConfigurationRequest"
      responses:
        '200':
          description: Successfully fetched export file configuration.
          content:
            application/json (Version 1.0.0):
               schema:
                  $ref: "#/components/schemas/ExportFileConfigurationResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
  


# Device Paramater Read Write APIs

  /companies/{company_id}/devices/{device_id}/parameters/write:
    post:
      operationId: RequestDeviceParameterDataWrite
      tags:
        - Parameters
      security:
        - bearerAuth: []
      summary: Write One or Many Parameters to Device
      description: >
        This API requests to Write One or Many Parameters to Device. Minimum 1 & Maximum 5 are Allowed.
        <br><br>
        Note:- Parameter details like parameter ID could be fetched using fetch all paramter API.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: "The company id which is linked to the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
        - name: device_id
          in: path
          required: true
          description: "The device id to fetch the parameters for, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/DeviceParameterWriteRequest"
      responses:
        "202":
          description: Request for writing parameters data is successfully Accepted.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeviceParameterWriteResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "403":
          $ref: "#/components/responses/403Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"


  /companies/{company_id}/devices/{device_id}/parameters/read:
    post:
      operationId: RequestParameterDataRead
      tags:
        - Parameters
      security:
        - bearerAuth: []
      summary: Read One or Many Parameters from Device
      description: >
        This API requests to Read One or Many Parameters from Device. Minimum 1 & Maximum 5 are Allowed.
        <br><br>
        Note:- Parameter details like parameter ID could be fetched using fetch all paramter API.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: "The company id which is linked to the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
        - name: device_id
          in: path
          required: true
          description: "The device id to fetch the parameters for, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/DeviceParameterReadRequest"
      responses:
        "202":
          description: Request for reading parameters data is successfully Accepted.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeviceParameterReadResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
        "403":
          $ref: "#/components/responses/403Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"


  /companies/{company_id}/devices/{device_id}/parameters:
    get:
      operationId: getAllParametersDataOfDevice
      tags:
        - Parameters
      security:
        - bearerAuth: []
      summary: Get All Parameters Data of a Device
      description: |
        This API will return All Parameters Data of a Device from HubIQ database.
        <br><br>
        Note:- As parameter are read from device on request basis thus this API will return value for the parameter which is read or written a value successfully, meaning this api may not return valu for all the parameter but a subset of it.
        <br><br>
        Note:- If Device parameter is locally updated then there could be discrepancy in result returned from this API, As Device is not proactively send parameter change event to HubIQ. 
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: company_id
          in: path
          required: true
          description: "The company id which is linked to the device, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
        - name: device_id
          in: path
          required: true
          description: "The device id to fetch the register data from, maximum size is 64 char"
          schema:
            type: string
            minimum: 1
            maximum: 64
            example: "1234"
      responses:
        "200":
          description: All Device parameters are successfully fetched.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/GetAllDeviceParametersResponse"
              examples:
                List of all parameters data of a device:
                  value:
                    data:
                      deviceId: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                      parameters:
                      - parameterId: <string>
                        values:
                        - key: Key Name, following pairs have some of then possible keys
                          value: value of key, following pairs have some of then possible values
                        - key: ParameterName
                          value: <string>
                        - key: ParameterValue
                          value: <string>
                        - key: DataType
                          value: <string>
                        - key: MinValue
                          value: <string>
                        - key: MaxValue
                          value: <string>
                        - key: DefaultValue
                          value: <string>
                        - key: Permission
                          value: <string>
                        - key: GroupName
                          value: <string>
                        - key: LastUpdatedOn
                          value: <string>
                        - key: LastUpdatedBy
                          value: <string>
                        - key: Description
                          value: <string>
                        - key: WriteStatus
                          value: <string>
                          description:  Possible values "PENDING", "ERROR" or NULL 
                        - key: ReadStatus
                          value: <string>
                          description:  Possible values "PENDING", "ERROR" or NULL 
                      - parameterId: <string>
                        values:
                        - key: Key Name, following pairs have some of then possible keys
                          value: value of key, following pairs have some of then possible values
                        - key: ParameterName
                          value: <string>
                        - key: ParameterValue
                          value: <string>
                        - key: DataType
                          value: <string>
                        - key: MinValue
                          value: <string>
                        - key: MaxValue
                          value: <string>
                        - key: DefaultValue
                          value: <string>
                        - key: Permission
                          value: <string>
                        - key: GroupName
                          value: <string>
                        - key: LastUpdatedOn
                          value: <string>
                        - key: LastUpdatedBy
                          value: <string>
                        - key: Description
                          value: <string>
                        - key: ParameterNumber
                          value: <string> 
                        - key: WriteStatus
                          value: <string>
                          description:  Possible values "PENDING", "ERROR" or NULL 
                        - key: ReadStatus
                          value: <string>
                          description:  Possible values "PENDING", "ERROR" or NULL                                                  
        "400":
          $ref: "#/components/responses/400Error"
        "403":
          $ref: "#/components/responses/403Error"
        "401":
          $ref: "#/components/responses/401Error"
        "405":
          $ref: "#/components/responses/405Error"
        "500":
          $ref: "#/components/responses/500Error"

# Targets APIs

  /companies/target/test-connection:
    post:
      operationId: TestTargetsConnection
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Tests connection to a new target.
      description: >
        Let's opeartor to Test connection to a new target.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/TargetConnectionTestRequest"
      responses:
        "200":
          description: Connection to target is tested successfully.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/TargetConnectionTestResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"

  /companies/{company_id}/targets:
    post:
      operationId: AddTargetsConfig
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Creates a new target.
      description: >
        Let's opeartor to create a new target.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/AddDeviceTargetsConfigRequest"
      responses:
        "200":
          description: Successfully created target.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/AddDeviceTargetsConfigResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"


  /companies/{company_id}/targets/{target_id}:
    put:
        operationId: UpdateTargetDetails
        tags:
          - Targets
        security:
          - bearerAuth: []
        summary: Update Target details
        description: >
          Lets operator to update Target details
        parameters:
          - in: header
            name: api-version
            required: true
            schema:
              type: string
              enum: ["1.0.0"]
              example: "1.0.0"
          - in: header
            name: auth-header
            required: true
            schema:
              type: string
              description: JWT Token
          - name: company_id
            in: path
            required: true
            description: The id of the company, maximum length 64 char.
            schema:
              type: string
              minimum: 1
              maximum: 64
          - in: path
            name: target_id
            required: true
            description: The id of the target to update, maximum size is 64 char.
            schema:
              type: string
              minimum: 1
              maximum: 64
        requestBody:
          required: true
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/UpdateTargetDetailsRequest"

        responses:
          "200":
            description: Successfully updated target details.
            content:
              application/json (Version 1.0.0):
                schema:
                  $ref: "#/components/schemas/UpdateTargetDetailsResponse"
          "400":
            $ref: "#/components/responses/400Error"
          "403":
            $ref: "#/components/responses/403Error"
          "404":
            $ref: "#/components/responses/404Error"
          "500":
            $ref: "#/components/responses/500Error"

    delete:
      operationId: DeleteTarget
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Delete a target for a company.
      description: >
        Let's opeartor to delete a target.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
        - in: path
          name: target_id
          required: true
          description: The id of the target to delete, maximum size is 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      responses:
        "200":
          description: Deleted target successfully
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/DeleteTargetResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"

  /companies/{company_id}/targets/list:
    get:
      operationId: GetTargetsList
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Fetch available list of targets for a company.
      description: >
        Let's opeartor to fetch available list of targets.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      responses:
        "200":
          description: Fetched targets successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FetchTargetsResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"


  /companies/{company_id}/devices/{device_id}/targets:
    get:
      operationId: GetTargetsOfaDevice
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Fetch mapped targets for a device.
      description: >
        Let's opeartor to fetch mapped targets for a device.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
        - in: path
          name: device_id
          required: true
          description: The id of the device, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      responses:
        "200":
          description: Fetched targets successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FetchDeviceTargetsResponse"
        "403":
          $ref: "#/components/responses/403Error"
        "500":
          $ref: "#/components/responses/500Error"
        "401":
          $ref: "#/components/responses/401Error"
        "404":
          $ref: "#/components/responses/404Error"



  # /companies/{company_id}/targets/{target_id}:
  #   get:
  #     operationId: GetTargetDetails
  #     tags:
  #       - Targets
  #     security:
  #       - bearerAuth: []
  #     summary: Fetch details of a target for a company.
  #     description: >
  #       Let's opeartor to fetch target details.
  #     parameters:
  #       - in: header
  #         name: api-version
  #         required: true
  #         schema:
  #           type: string
  #           enum: ["1.0.0"]
  #           example: "1.0.0"
  #       - in: header
  #         name: auth-header
  #         required: true
  #         schema:
  #           type: string
  #           description: JWT Token
  #       - in: path
  #         name: company_id
  #         required: true
  #         description: The id of the company, maximum length 64 char.
  #         schema:
  #           type: string
  #           minimum: 1
  #           maximum: 64
  #       - in: path
  #         name: target_id
  #         required: true
  #         description: The id of the target to fetch, maximum size is 64 char.
  #         schema:
  #           type: string
  #           minimum: 1
  #           maximum: 64
  #     responses:
  #       "200":
  #         description: Fetched target details successfully
  #         content:
  #           application/json:
  #             schema:
  #               $ref: "#/components/schemas/FetchTargetDetailsResponse"
  #       "403":
  #         $ref: "#/components/responses/403Error"
  #       "500":
  #         $ref: "#/components/responses/500Error"
  #       "401":
  #         $ref: "#/components/responses/401Error"
  #       "404":
  #         $ref: "#/components/responses/404Error"

    

  /companies/{company_id}/targets/map-devices:
    post:
      operationId: AddTargets
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Map targets to route device data
      description: >
        Let's operator to map targets to a group of devices in a company.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/AddDeviceTargetsRequest"
      responses:
        "200":
          description: Successfully addded device to target mapping.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/AddDeviceTargetsResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"

  /companies/{company_id}/devices/{device_id}/targets/map:
   put:
      operationId: EditTargetsOfDevice
      tags:
        - Targets
      security:
        - bearerAuth: []
      summary: Map targets to a device for routing device data
      description: >
        Let's operator to map targets to a device in a company.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
        - in: path
          name: device_id
          required: true
          description: The id of the device, maximum length 64 char.
          schema:
            type: string
            minimum: 1
      requestBody:
        required: true
        content:
          application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/MapSingleDeviceTargetsRequest"
      responses:
        "200":
          description: Successfully addded device to target mapping.
          content:
            application/json (Version 1.0.0):
              schema:
                $ref: "#/components/schemas/MapSingleDeviceTargetsResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"



  #Notification Subscription APIs
  /companies/{company_id}/subscriptions/alarms:
    get:
      operationId: GetAlarmSubscriptions
      tags:
        - Notifications
      security:
        - bearerAuth: []
      summary: Get subscriptions
      description: Retrieve subscriptions filtered by user ID
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - name: userId
          in: query
          description: Filter subscriptions by user ID.
          required: false
          schema:
            type: string
          example: "user123"

      responses:
        "200":
          description: Subscriptions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAlarmSubscriptionsResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"
  
  # Alarm Subscription APIs

    post:
      operationId: CreateAlarmSubscription
      tags:
        - Notifications
      security:
        - bearerAuth: []
      summary: Allows user to subscribe to one or more alarms
      description: Allows user to subscribe to one or more alarms if it does not exist already.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64            
      requestBody:
        required: true
        content:
           application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/CreateAlarmSubscriptionRequest"
      responses:
        "201":
          description: Successfully created alarm subscription.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAlarmSubscriptionResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"

  /companies/{company_id}/subscriptions/alarms/{subscription_id}:
    put:
      operationId: UpdateAlarmSubscription
      tags:
        - Notifications
      security:
        - bearerAuth: []
      summary: Update a subscription
      description: Allows a user to modify an existing alarm subscription. An empty array of alarms will delete the subscription resource.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64                
        - name: subscriptionId
          in: path
          description: The ID of the subscription to update.
          required: true
          schema:
            type: string
          example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac9"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAlarmSubscriptionRequest"
      responses:
        "200":
          description: Subscription updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateAlarmSubscriptionResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"
  

  #Device Subscription APIs



  /companies/{company_id}/subscriptions/device:
    post:
      operationId: CreateDeviceSubscription
      tags:
        - Notifications
      security:
        - bearerAuth: []
      summary: Allows user to subscribe to a device.
      description: Allows user to subscribe to a device.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64            
      requestBody:
        required: true
        content:
           application/json (Version 1.0.0):
            schema:
              $ref: "#/components/schemas/CreateDeviceSubscriptionRequest"
      responses:
        "201":
          description: Successfully created alarm subscription for device(s).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateDeviceSubscriptionResponse"
        "400":
          $ref: "#/components/responses/400Error"
        "500":
          $ref: "#/components/responses/500Error"


  /companies/{company_id}/subscriptions/{subscriptionId}:
    delete:
      operationId: DeleteDeviceSubscription
      tags:
        - Notifications
      security:
        - bearerAuth: []
      summary: Delete a subscription for a device
      description: Allows a user to delete an alarm subscription for a device.
      parameters:
        - in: header
          name: api-version
          required: true
          schema:
            type: string
            enum: ["1.0.0"]
            example: "1.0.0"
        - in: header
          name: auth-header
          required: true
          schema:
            type: string
            description: JWT Token      
        - name: subscriptionId
          in: path
          description: The ID of the subscription to delete.
          required: true
          schema:
            type: string
          example: "sub_abc123"
        - in: path
          name: company_id
          required: true
          description: The id of the company, maximum length 64 char.
          schema:
            type: string
            minimum: 1
            maximum: 64
      responses:
        "200":
          description: Device subscription deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteSubscriptionResponse"
        "404":
          $ref: "#/components/responses/404Error"
        "500":
          $ref: "#/components/responses/500Error"        

#Models

components:
  schemas:

# Move Devices Request and Response

    MoveDevicesRequest:
      type: object
      required:
        - newCompanyId
        - devices
      properties:
        newCompanyId:
          type: string
          description: "The company id to which device will be moved"
          example: "1234-f44j-44f4-44f"
          maximum: 64
        devices:
          type: array
          minimum: 1
          maximum: 5
          items:
            type: object
            required:
              - deviceType
              - deviceId
            properties:
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
                description: "The type of the device"
              deviceId:
                type: string
                description: "ID of device to move"
                example: "4CE0460D0G"
                maximum: 64

    MoveDevicesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              deviceId:
                type: string
                description: "The device's unique id"
                example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                maximum: 64
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
                description: "The type of the device"
              companyId:
                type: string
                description: The updated company ID.
                example: "1234-f44j-44f4-44f"
                maximum: 64
              companyName:
                type: string
                description: The updated company's name.
                example: "Siemens"
                maximum: 64
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: "unique error id - uuid"
                example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
              code:
                type: string
                description: "unique error code"
                example: "FWENQ-0x00000001"
              title:
                type: string
                description: "Error title"
                example: "Bad Request"
              status:
                type: number
                description: "HTTP Status code"
                example: "400"
              details:
                type: string
                description: "error message"
                example: "Invalid Serial number"
              meta:
                type: object
                properties:
                  deviceType:
                    type: string
                    enum:
                      - "Mag8000-4G"
                      - "Mag8000-LoRa"
                      - "CC220"
                      - "MS200"
                      - "IoTRadar"
                      - "Mag8000-4G-Flex"
                      - "Mag8000-LoRaGateway"
                    example: "Mag8000-4G"
                    description: "The type of the device"
                  deviceId:
                    type: string
                    description: "ID of device to move"
                    example: "4CE0460D0G"
                    maximum: 64
              correlationId:
                type: string
                description: "transaction unique id"
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"


# Firmware Update Request and Response
    FirmwareUpdateRequest:
      type: object
      properties:
        devices:
          type: array
          minimum: 1
          maximum: 15
          items:
            type: object
            required:
              - deviceType
              - deviceId
              - rolledoutFirmwareVersion
            properties:
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
              deviceId:
                type: string
                minimum: 1
                maximum: 64
                example: "12345"
              rolledoutFirmwareVersion:
                type: string
                minimum: 1
                maximum: 16
                example: "03.00.00"


    FirmwareUpdateResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            devices:
              type: array
              items:
                type: object
                properties:
                  deviceType:
                    type: string
                    enum:
                      - "Mag8000-4G"
                      - "Mag8000-LoRa"
                      - "CC220"
                      - "MS200"
                      - "IoTRadar"
                      - "Mag8000-4G-Flex"
                      - "Mag8000-LoRaGateway"
                    example: "Mag8000-4G"
                  deviceId:
                    type: string
                    example: "12345"
                  rolledoutFirmwareVersion:
                    type: string
                    example: "03.00.00"
          example:
              devices:
                - deviceType: "Mag8000-4G"
                  deviceId: "12345"
                  rolledoutFirmwareVersion: "03.00.00"
                - deviceType: "Mag8000-4G"
                  deviceId: "45678"
                  rolledoutFirmwareVersion: "01.00.00"
                - deviceType: "CC220"
                  deviceId: "12345"
                  rolledoutFirmwareVersion: "01.00.00"
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: "unique error id - uuid"
                example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
              code:
                type: string
                description: "unique error code"
                example: "FWENQ-0x00000001"
              title:
                type: string
                description: "Error title"
                example: "Bad Request"
              status:
                type: number
                description: "HTTP Status code"
                example: "400"
              details:
                type: string
                description: "error message"
                example: "Invalid Serial number"
              meta:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      type: object
                      properties:
                        deviceType:
                          type: string
                          enum:
                            - "Mag8000-4G"
                            - "Mag8000-LoRa"
                            - "CC220"
                            - "MS200"
                            - "IoTRadar"
                            - "Mag8000-4G-Flex"
                            - "Mag8000-LoRaGateway"
                          example: "Mag8000-4G"
                        deviceId:
                          type: string
                          example: "12345"
                        rolledoutFirmwareVersion:
                          type: string
                          example: "03.00.00"
                example:
                    devices:
                      - deviceType: "Mag8000-4G"
                        deviceId: "12345"
                        rolledoutFirmwareVersion: "03.00.00"
                      - deviceType: "Mag8000-4G"
                        deviceId: "45678"
                        rolledoutFirmwareVersion: "01.00.00"
                      - deviceType: "CC220"
                        deviceId: "12345"
                        rolledoutFirmwareVersion: "01.00.00"
              correlationId:
                type: string
                description: "transaction unique id"
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"
    

# Fetch Targets Request & Response
    FetchTargetsRequest:
      type: object
      description: next_token and previous_token both must not be present in the same request
      properties:
        pageSize:
          type: integer
          example: 15
          default: 15
          enum:
            - 15
            - 30
            - 50
          description: "Optional. The maximum of values to fetch. Will add a 'NextToken' key to fetch the next page. Defaults to 15"
        nextToken:
          type: string
          default: None
          example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
          description: "A base64 encoded string to fetch the next page of the paginated result."
        previousToken:
          type: string
          default: None
          example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
          description: "A base64 encoded string to fetch the previous page of the paginated result."
        sorting:
          type: object
          properties:
            sortBy:
              default: CreatedOn
              description: the attribute/column on which we want to apply sorting & Default sorting would be based on CreatedOn
              example: CreatedOn
              enum:
                - CreatedOn
            sortOrder:
              type: string
              default: asc
              description:  choose option asc if want to sort in ascending and desc for descending order
              example: asc
              enum:
                - asc
                - desc
        filters:
          type: array
          items:
            type: object
            required:
              - key
              - condition
              - value
            properties:
              key:
                type: string
                enum:
                  - TargetType
                  - Option_1
              condition:
                type: string
                enum:
                  - Equals
                  - Contains
              value:
                type: string
                maximum: 32

    FetchTargetsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            targets:
              type: array
              items:
                type: object
                properties:
                  targetGroup: 
                    type: string
                    example: "Application or SFTP/FTP or EMAIL"
                  targetId:
                    type: string
                    example: 1-66f3a9dc-4924ac09759b99e51766d14d
                  targetAttributes:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: type
                        value:
                          type: string
                          example: IIH Monitor App
          example: >
            {
              "targets": [
                {
                  "targetGroup": "Application",
                  "targetId": "1-66f3a9dc-4924ac09759b99e51766d14d",
                  "targetAttributes": [
                    {
                      "key": "Key Name, following pairs have some of then possible keys",
                      "value": "value of key, following pairs have some of then possible values"
                    },
                    {
                      "key": "type",
                      "value": "IIH Monitor App"
                    },
                    {
                      "key": "name",
                      "value": "IIH Monitor App 1"
                    },
                    {
                      "key": "customerId",
                      "value": "1234-f44j-44f4-44f"
                    }
                  ]
                },
                {``
                  "targetGroup": "Application",
                  "targetId": "1-66f3a9dc-4924ac09759b99e51766d14e",
                  "targetAttributes": [
                    {
                      "key": "Key Name, following pairs have some of then possible keys",
                      "value": "value of key, following pairs have some of then possible values"
                    },
                    {
                      "key": "type",
                      "value": "SIWA Blockage App"
                    },
                    {
                      "key": "name",
                      "value": "SIWA Blockage App 1"
                    },
                    {
                      "key": "customerId",
                      "value": "1234-f44j-44f4-44f"
                    }
                  ]
                },
                {
                  "targetGroup": "Server",
                  "targetId": "1-66f3a9dc-4924ac09759b99e51766d14f",
                  "targetAttributes": [
                    {
                      "key": "Key Name, following pairs have some of then possible keys",
                      "value": "value of key, following pairs have some of then possible values"
                    },
                    {
                      "key": "url",
                      "value": "https://xyz.com"
                    },
                    {
                      "key": "userName",
                      "value": "xyz@siemens.com.com"
                    },
                    {
                      "key": "password",
                      "value": "xxxxxxxxxx"
                    }
                  ]
                },
                {
                  "targetGroup": "email",
                  "targetId": "1-66f3a9dc-4924ac09759b99e51766d14f",
                  "targetAttributes": [
                    {
                      "key": "Key Name, following pairs have some of then possible keys",
                      "value": "value of key, following pairs have some of then possible values"
                    },
                    {
                      "key": "email",
                      "value": "xyz@siemens.com"
                    }
                  ]
                }
              ]
            }
            
    FetchDeviceTargetsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            targets:
              type: array
              items:
                type: string
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"

         

    FetchTargetDetailsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            targetId:
              type: string
              example: "1-66f3a9dc-4924ac09759b99e51766d14d"
            targetGroup:
              type: string
              example: "Application/Server/Email"
            targetAttributes:
              type: array
              items:
                type: object
                required:
                  - key
                  - value
                properties:
                  key:
                    type: string
                    example: type
                  value:
                    type: string
                    example: SIWA Blockage
                  email:
                    type: string
                    example: "xyz@siemens.com"
                example:
                  key: type
                  value: SIWA Blockage
              example:
                - key: type
                  value: SIWA Blockage
                - key: name
                  value: SIWA Blockage 1
                - key: customerId
                  value: 1234-f44j-44f4-44f
                - key: serverUrl
                  value: https://serverurl.com
                - key: email
                  value: xyz@siemens.com


    # Delete Target Response
    DeleteTargetResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully deleted target."
            targetId:
              type: string
              example: "1-66f3a9dc-4924ac09759b99e51766d14d"

    # Add Target Data Request & Response
    AddDeviceTargetsRequest:
      type: object
      required:
        - deviceIds
        - targets
      properties:
        deviceIds:
          type: array
          items:
            type: string
            minimum: 1
            maximum: 64
          example: 
          - "device-uuid-1"
          - "device-uuid-2"
        targets:
          type: array
          items:
            type: object
            required:
              - targetGroup
              - targetId
            properties:
              targetGroup:
                type: string
                example: Application
              targetId:
                type: string
                minimum: 1
                maximum: 64
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"
          example: [
            {
              targetGroup: "Application", 
              targetId: "1-66f3a9dc-4924ac09759b99e51766d14d"
            },
            {
              targetGroup: "Server", 
              targetId: "1-66f3a9dc-4924ac09759b99e51766d14e"
            },
            {
              targetGroup: "Email", 
              targetId: "1-66f3a9dc-4924ac09759b99e51766d14f"
            }
          ]  
          minimum: 1
          maximum: 20
          description: "Number of targets should atleast be 1 and maximum 20"

    AddDeviceTargetsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully added device to target mapping"
              description: Successfully created target.
 
 
# Map Target for a device Request & Response
    MapSingleDeviceTargetsRequest:
      type: object
      required:
        - targets
      properties:
        targets:
          type: array
          items:
            type: string
          example: [
               "1-66f3a9dc-4924ac09759b99e51766d14d",
               "1-66f3a9dc-4924ac09759b99e51766d14e",
               "1-66f3a9dc-4924ac09759b99e51766d14f"
          ]  
          minimum: 1
          maximum: 20
          description: "Number of targets should atleast be 1 and maximum 20"

    MapSingleDeviceTargetsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully added device to target mapping"
              description: Successfully created target.         

              

    UpdateTargetDetailsRequest:
      type: object
      required:
        - targetGroup
        - targetAttributes
      properties:
        targetGroup:
          type: string
          example: "Application/Server/Email"
        targetAttributes:
          type: array
          maximum: 20
          items:
            type: object
            properties:
              key:
                type: string
                example: type
              value:
                type: string
                example: when key is either "targetType" or "protocol" the allowed values are fixed, please refer example for allowed values.
          example:
            - key: Key Name, following pairs have some of then possible keys
              value: value of key, following pairs have some of then possible values
            - key: targetType
              value: allowed values "siwaleak/ftp/mail"
            - key: protocol
              value: allowed values "mqtt/ftp/sftp/smtp"
            - key: name
              value: SIWA Blockage 1
            - key: customerId
              value: 1234-f44j-44f4-44f
            - key: serverUrl
              value: https://serverurl.com
            - key: email
              value: "xyz@siemens.com"

    UpdateTargetDetailsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully updated target details."
            targetId:
              type: string
              example: "1234-f44j-44f4-44f"
              description:  "UUID of target record"

# Add Target Data Config Request & Response

    AddDeviceTargetsConfigRequest:
      type: object
      required:
        - targetGroup
        - targetAttributes
      properties:
        targetGroup:
          type: string
          example: "Application/Server/Email"
        targetAttributes:
          type: array
          maximum: 20
          items:
            type: object
            required:
              - key
              - value
            properties:
              key:
                type: string
                example: type
              value:
                type: string
                example: SIWA Blockage
                description: when key is either "targetType" or "protocol" the allowed values are fixed, please refer example for allowed values.
          description: Note:- apart form targetType and protocol all other keys values are just for reprsentational purpose.
          example:
            - key: Key Name, following pairs have some of then possible keys
              value: value of key, following pairs have some of then possible values
            - key: targetType
              value: allowed values "siwaleak/ftp/mail"
            - key: protocol
              value: allowed values "mqtt/ftp/sftp/smtp"
            - key: name
              value: SIWA Blockage 1
            - key: customerId
              value: 1234-f44j-44f4-44f
            - key: serverUrl
              value: https://serverurl.com
            - key: email (only in case of Email type)
              value: "xyz@siemens.com"

 
  
    AddDeviceTargetsConfigResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully created target."
              description: Successfully created target.
            targetId:
              type: string
              example: "1-66f3a9dc-4924ac09759b99e51766d14d"
              description:  "UUID of new target record"


# Add Target Data Config Request & Response

    TargetConnectionTestRequest:
      type: object
      required:
        - targetGroup
        - targetAttributes
      properties:
        targetGroup:
          type: string
          example: "Application/Server/Email"
        targetAttributes:
          type: array
          maximum: 20
          items:
            type: object
            required:
              - key
              - value
            properties:
              key:
                type: string
                example: type
              value:
                type: string
                example: SIWA Blockage
                description: when key is either "targetType" or "protocol" the allowed values are fixed, please refer example for allowed values.
          description: Note:- apart form targetType and protocol all other keys values are just for reprsentational purpose.
          example:
            - key: Key Name, following pairs have some of then possible keys
              value: value of key, following pairs have some of then possible values
            - key: targetType
              value: allowed values "siwaleak/ftp/mail"
            - key: protocol
              value: allowed values "mqtt/ftp/sftp/smtp"
            - key: username
              value: SIWA Blockage 1
            - key: password
              value: 1234-f44j-44f4-44f
            - key: serverUrl
              value: https://serverurl.com
            - key: ftpType
              value: "implicit/explicit" # only in case of ftp/sftp type

    TargetConnectionTestResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully created target."
              description: Successfully created target.

   
# Create Company Request & Response

    CreateCompanyRequest:
      type: object
      required:
        - name
        - parentCompanyId
      properties:
        name:
          type: string
          example: "new_company_pvt_ltd#1"
          minimum: 2
          maximum: 64
          description: "Company name. The length must be at least 2"
        parentCompanyId:
          type: string
          example: "1234-f44j-44f4-44f"
          minimum: 1
          maximum: 64
          description: "Must be requested using suitable company API. This parameter specifies the parent company of the new company."

    CreateCompanyResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            companyId:
              type: string
              description: The id of the company.
            companyName:
              type: string
              example: "new_company_pvt_ltd#1"
              description:  "Comnapny Name"
            parentCompanyId:
              type: string
              example: "1234-f44j-44f4-44f"
              description: "Parent company ID"

# Get Company or its child Company Response

    ListCompaniesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            companyId:
              type: string
              description: The id of the company.
            companyName:
              type: string
              description: The name of the company.
            children:
              type: array
              items:
                type: object
                properties:
                  companyId:
                    type: string
                    description: The id of the child company.
                  companyName:
                    type: string
                    description: The name of the child company.
                  children:
                    type: array
                    items:
                      type: object
                      properties:
                        companyId:
                          type: string
                          description: The id of the child company.
                        companyName:
                          type: string
                          description: The name of the child company.

# Delete Company Response

    DeleteCompanyResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
            companyId:
              type: string
              example: "1234-f44j-44f4-44f"
              description: The id of the company.

# Update Company Request and Response
    UpdateCompanyRequest:
      type: object
      description: anyone of attribute must be passed with appropriate value.
      properties:
        companyName:
          type: string
          example: "new_company_pvt_ltd#1"
          minimum: 2
          maximum: 64
          description: "Company name. The length must be at least 2"
        parentCompanyId:
          type: string
          example: "1234-f44j-44f4-44f"
          description: "Parent company ID"

    UpdateCompanyResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully updated company name."
              minimum: 1
              maximum: 50
            companyId:
              type: string
              example: "1234-f44j-44f4-44f"
              description:  "UUID of company record"
              minimum: 1
              maximum: 64

# Claim Device Request & Response

    DeviceClaimRequest:
      type: object
      properties:
        devices:
          type: array
          minimum: 1
          maximum: 10
          items:
            type: object
            description: any one of the four device identifier is required to be passed
            required:
              - deviceType
            properties:
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
                description: "The type of the device"
              serialNumber:
                type: string
                description: "Serial number of device"
                example: "4CE0460D0G"
                maximum: 32
              iccid:
                type: string
                description: "The id for MAG 4G devices"
                example: "4CE0460D0G"
                maximum: 32
              imei:
                  type: string
                  example: "123564894894561651"
                  description: IMEI of the device
                  maximum: 32
              deveui:
                type: string
                description: "The id for MAG LORA devices"
                example: "4CE0460D0G"
                maximum: 32
              macAddress:
                type: string
                description: "MAC Address of the device"
                example: "00-B0-D0-63-C2-26"
                maximum: 32
              deviceId:
                type: string
                description: "The device's unique id"
                example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                maximum: 64

    DeviceClaimResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              companyId:
                type: string
                description: The current company or the requested company's id.
              deviceId:
                type: string
                description: "The device's unique id"
                example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
                description: "The type of the device"
              serialNumber:
                type: string
                description: "Serial number of device"
                example: "4CE0460D0G"
              iccid:
                type: string
                description: "The id for MAG 4G devices"
                example: "4CE0460D0G"
              deveui:
                type: string
                description: "The id for MAG LORA devices"
                example: "4CE0460D0G"
              macAddress:
                type: string
                description: "MAC Address of the device"
                example: "00-B0-D0-63-C2-26"
              imei:
                type: string
                description: The device's IMEI number
                example: "355882069673699"
              mlfb:
                type: string
                description: The device's MLFB number
                example: "3VA6225-6HN31-0DK0"
              claimedStatus:
                type: string
                description: "The device's claimed status"
                enum:
                  - "CLAIMED"
                  - "UNCLAIMED"
                example: "CLAIMED"
              claimedOn:
                type: string
                example: 
                description: Timestamp of when the device was claimed.
              provisionedOn:
                type: string
                example: 
                description: Timestamp of when the device was provisioned/registered.
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: "unique error id - uuid"
                example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
              code:
                type: string
                description: "unique error code"
                example: "FWENQ-0x00000001"
              title:
                type: string
                description: "Error title"
                example: "Bad Request"
              status:
                type: number
                description: "HTTP Status code"
                example: "400"
              details:
                type: string
                description: "error message"
                example: "Invalid Serial number"
              meta:
                type: object
                properties:
                  deviceType:
                    type: string
                    enum:
                      - "Mag8000-4G"
                      - "Mag8000-LoRa"
                      - "CC220"
                      - "MS200"
                      - "IoTRadar"
                      - "Mag8000-4G-Flex"
                      - "Mag8000-LoRaGateway"
                    example: "Mag8000-4G"
                    description: "The type of the device"
                  serialNumber:
                    type: string
                    description: "Serial number of device"
                    example: "4CE0460D0G"
                  iccid:
                    type: string
                    description: "The id for MAG 4G devices"
                    example: "4CE0460D0G"
                  deveui:
                    type: string
                    description: "The id for MAG LORA devices"
                    example: "4CE0460D0G"
                  macAddress:
                    type: string
                    description: "MAC Address of the device"
                    example: "00-B0-D0-63-C2-26"
              correlationId:
                type: string
                description: "transaction unique id"
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"


# Get Device Request

    GetDevicesRequest:
      type: object
      description: next_token and previous_token both must not be present in the same request
      properties:
        pageSize:
          type: integer
          example: 15
          default: 15
          enum:
            - 15
            - 30
            - 50
          description: "Optional. The maximum of values to fetch. Will add a 'NextToken' key to fetch the next page. Defaults to 15"
        nextToken:
          type: string
          default: None
          example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
          description: "A base64 encoded string to fetch the next page of the paginated result."
        previousToken:
          type: string
          default: None
          example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
          description: "A base64 encoded string to fetch the previous page of the paginated result."
        subchild:
          type: string
          default: True
          example: True
          enum:
            - True
            - False
          description: "If False is passed then same level will be returned, and if True is passed or this parameter is not passed then the whole hierarchy will be returned"
        sorting:
          type: object
          properties:
            sortBy:
              default: ProvisionedOn
              type: string
              description: the attribute/column on which we want to apply sorting & Default sorting would be based on ProvisionedOn
              example: ProvisionedOn
              enum:
                - SerialNumber
                - ProvisionedOn
                - DeviceType
                - CurrentFirmwareVersion
                - InAlarmState
                - InErrorState
                - RolledoutFirmwareVersion
            sortOrder:
              type: string
              default: asc
              description:  choose option asc if want to sort in ascending and desc for descending order
              example: asc
              enum:
                - asc
                - desc
        filters:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
                enum:
                  - SerialNumber
                  - ProvisionedOn
                  - DeviceType
                  - CurrentFirmwareVersion
                  - InAlarmState
                  - InErrorState
                  - RolledoutFirmwareVersion
                  - ClaimedOn
                  - CompanyName
                  - DeviceApplicationIdentifier
              condition:
                type: string
                enum:
                  - Equals
                  - Contains
              value:
                type: string
                maximum: 32

# Get Device Response

    GetDevicesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            devices:
              type: array
              description: The list of devices belonging directly to the company.
              items:
                type: object
                properties:
                  companyId:
                    type: string
                    description: The current company or the requested company's id.
                  companyName:
                    type: string
                    description: The current company or the requested company's id.
                  deviceId:
                    type: string
                    description: "The device's unique id"
                    example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                  deviceApplicationIdentifier:
                    type: string
                    description: "The device's application identifier"
                    example: "device_unique_name" 
                  deviceType:
                    type: string
                    enum:
                      - "Mag8000-4G"
                      - "Mag8000-LoRa"
                      - "CC220"
                      - "MS200"
                      - "IoTRadar"
                      - "Mag8000-4G-Flex"
                      - "Mag8000-LoRaGateway"
                    example: "Mag8000-4G"
                    description: "The type of the device"
                  serialNumber:
                    type: string
                    description: "Serial number of device"
                    example: "4CE0460D0G"
                  iccid:
                    type: string
                    description: "The id for MAG 4G devices"
                    example: "4CE0460D0G"
                  deveui:
                    type: string
                    description: "The id for MAG LORA devices"
                    example: "4CE0460D0G"
                  macAddress:
                    type: string
                    description: "MAC Address of the device"
                    example: "00-B0-D0-63-C2-26"
                  imei:
                    type: string
                    description: The device's IMEI number
                    example: "355882069673699"
                  mlfb:
                    type: string
                    description: The device's MLFB number
                    example: "3VA6225-6HN31-0DK0"
                  claimedStatus:
                    type: string
                    description: "The device's claimed status"
                    enum:
                      - "CLAIMED"
                      - "UNCLAIMED"
                    example: "CLAIMED"
                  connectivityStatus:
                    type: string
                    description: The device's status.
                    enum:
                      - "CONNECTED"
                      - "DISCONNECTED"
                      - "UNKNOWN"
                    example: "CONNECTED"
                  claimedOn:
                    type: string
                    example: 
                    description: Timestamp of when the device was claimed.
                  provisionedOn:
                    type: string
                    example: 
                    description: Timestamp of when the device was provisioned/registered.
                  lastConnectedOn:
                    type: string
                    description: Timestamp of last communication with the device.
                  currentFirmwareVersion:
                    type: string
                    example: "01.00.00"
                    description: Device Current Firmware Version.
                  isTargetMapped:
                    type: boolean
                    example: true
                    description: Indicates if Device has any mapped target. 
                  deviceSubscriptionId:
                    type: string
                    example: f5d7c5d5-3d05-4b0a-a7a1-55f1adf69af0
                    description: Device subscriptionId of  the user for the given device.  
                  inAlarmState:
                    type: boolean
                    example: true
                    description: Device Alarm Status.
                  inErrorState:
                    type: boolean
                    example: true
                    description: Device Error Status.
                  rolledoutFirmwareStatus:
                    type: string
                    enum:
                      - "rolled_out"
                      - "queued"
                      - "download_started"
                      - "download_successful"
                      - "download_failed"
                      - "installation_started"
                      - "installation_failed"
                      - "installation_complete"
                    example: "download_started"
                    description: Device Rolledout Firmware Status.
                  rolledoutFirmwareVersion:
                    type: string
                    example: "02.00.00"
                    description: Device RolledOut Firmware Version.
                  deviceLocation:
                    type: string
                    example: "bangalore,India"
                    description: Device Location as text.
                  latitude:
                    type: number
                    format: Decimal(8,6)
                    example: "49.0069"
                    description: Device Latitude.
                  longitude:
                    type: number
                    format: Decimal(9,6)
                    example: "8.4037"
                    description: Device Longitude.
            totalDeviceCount:
              type: integer
              description: The total number of devices.
              example: 550
            pageSize:
              type: integer
              example: 15
              default: 15
              enum:
                - 15
                - 30
                - 50
              description: "Optional. The maximum of values to fetch. Will add a 'NextToken' key to fetch the next page. Defaults to 15"
            nextToken:
              type: string
              default: None
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: "A base64 encoded string to fetch the next page of the paginated result."
            previousToken:
              type: string
              default: None
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: "A base64 encoded string to fetch the previous page of the paginated result."
            subchild:
              type: string
              default: True
              example: True
              enum:
                - True
                - False
              description: "If False is passed then same level will be returned, and if True is passed or this parameter is not passed then the whole hierarchy will be returned"
            sorting:
              type: object
              properties:
                sortBy:
                  default: ProvisionedOn
                  description: the attribute/column on which we want to apply sorting & Default sorting would be based on ProvisionedOn
                  example: ProvisionedOn
                  enum:
                    - SerialNumber
                    - ProvisionedOn
                    - DeviceType
                    - CurrentFirmwareVersion
                    - InAlarmState
                    - InErrorState
                    - RolledoutFirmwareVersion
                sortOrder:
                  type: string
                  default: asc
                  description:  choose option asc if want to sort in ascending and desc for descending order
                  example: asc
                  enum:
                    - asc
                    - desc
            filters:
              type: array
              items:
                type: object
                properties:
                  key:
                    type: string
                    enum:
                      - SerialNumber
                      - ProvisionedOn
                      - DeviceType
                      - CurrentFirmwareVersion
                      - InAlarmState
                      - InErrorState
                      - RolledoutFirmwareVersion
                      - ClaimedOn
                      - CompanyName
                      - DeviceApplicationIdentifier
                  condition:
                    type: string
                    enum:
                      - Equals
                      - Contains
                  value:
                    type: string

# Get a device response

    GetOneDeviceResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            companyId:
              type: string
              description: The current company or the requested company's id.
            companyName:
              type: string
              description: The current company or the requested company's id.
            deviceId:
              type: string
              description: "The device's unique id"
              example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
            deviceType:
              type: string
              enum:
                - "Mag8000-4G"
                - "Mag8000-LoRa"
                - "CC220"
                - "MS200"
                - "IoTRadar"
                - "Mag8000-4G-Flex"
                - "Mag8000-LoRaGateway"
              example: "Mag8000-4G"
              description: "The type of the device"
            serialNumber:
              type: string
              description: "Serial number of device"
              example: "4CE0460D0G"
            iccid:
              type: string
              description: "The id for MAG 4G devices"
              example: "4CE0460D0G"
            deveui:
              type: string
              description: "The id for MAG LORA devices"
              example: "4CE0460D0G"
            macAddress:
              type: string
              description: "MAC Address of the device"
              example: "00-B0-D0-63-C2-26"
            imei:
              type: string
              description: The device's IMEI number
              example: "355882069673699"
            mlfb:
              type: string
              description: The device's MLFB number
              example: "3VA6225-6HN31-0DK0"
            claimedStatus:
              type: string
              description: "The device's claimed status"
              enum:
                - "CLAIMED"
                - "UNCLAIMED"
              example: "CLAIMED"
            connectivityStatus:
              type: string
              description: The device's status.
              enum:
                - "CONNECTED"
                - "DISCONNECTED"
                - "UNKNOWN"
              example: "CONNECTED"
            claimedOn:
              type: string
              example: 
              description: Timestamp of when the device was claimed.
            provisionedOn:
              type: string
              example: 
              description: Timestamp of when the device was provisioned/registered.
            lastConnectedOn:
              type: string
              description: Timestamp of last communication with the device.
            currentFirmwareVersion:
              type: string
              example: "01.00.00"
              description: Device Current Firmware Version.
            isTargetMapped:
              type: boolean
              example: true
              description: Indicates if Device has any mapped target.
            inAlarmState:
              type: boolean
              example: true
              description: Device Alarm Status.
            inErrorState:
              type: boolean
              example: true
              description: Device Error Status.
            rolledoutFirmwareStatus:
              type: string
              enum:
                - "rolled_out"
                - "queued"
                - "download_started"
                - "download_successful"
                - "download_failed"
                - "installation_started"
                - "installation_failed"
                - "installation_complete"
              example: "download_started"
              description: Device Rolledout Firmware Status.
            rolledoutFirmwareVersion:
              type: string
              example: "02.00.00"
              description: Device RolledOut Firmware Version.
            deviceLocation:
              type: string
              example: "bangalore,India"
              description: Device Location as text.
            latitude:
              type: number
              format: Decimal(8,6)
              example: "49.0069"
              description: Device Latitude.
            longitude:
              type: number
              format: Decimal(9,6)
              example: "8.4037"
              description: Device Longitude.
            


# Delete Device Response

    DeleteDeviceResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully deleted device."
            deviceId:
              type: string
              example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
              description:  "UUID of device record"

#Telemetry Data Response

    GetMeasurementDataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deviceId:
              type: string
              description: "The device's unique id"
              example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
            nextToken:
              type: string
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: A base64 encoded token to fetch the next page of the paginated result, until the last results have been fetched.
            units:
              type: array
              items:
                type: object
                properties:
                  attributeName:
                    type: string
                    description: "name of attribute"
                    example: "BatteryCapacity"
                  attributeUnit:
                    type: string
                    description: "Unit of attribute"
                    example: "%"
            values:
              type: array
              maximum: 2000
              items:
                type: object
                properties:
                  collectedTimestamp:
                    type: string
                    description: Timestamp when the message was collected in the module.
                  attributes:
                    type: array
                    items:
                      type: object
                      properties:
                        attributeName:
                          type: string
                          description: "name of attribute"
                          example: "BatteryCapacity"
                        attributeValue:
                          type: string
                          description: "Value of attribute"
                          example: "20"
 

    GetLatestMeasurementDataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deviceId:
              type: string
              description: "The device's unique id"
              example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
            collectedTimestamp:
              type: string
              description: Timestamp when the message was collected in the module.
            attributes:
              type: array
              items:
                type: object
                properties:
                  attributeName:
                    type: string
                    description: "name of attribute"
                    example: "BatteryCapacity"
                  attributeValue:
                    type: string
                    description: "Value of attribute"
                    example: "20"
                  attributeUnit:
                    type: string
                    description: "Unit of attribute "
                    example: "m3"

# Export file configuration

    GetExportFileConfigurationResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            exportFileConfigurationId:
              type: string
              description: "The unique identifier for the export file configuration."
            delimiter:
              type: string
              description: "The delimiter used in the export file (e.g., comma, semicolon)."
              example: ","
            exportFileformat:
              type: string
              description: The format of the export file (e.g., Standard).
              example: "Standard"
            timezone:
              type: string
              description: The timezone to be used for the export file.
              example: "UTC"

    ExportFileConfigurationRequest:
      type: object
      required:
        - delimiter
        - exportFileformat
        - timezone
      properties:
        exportFileConfigurationId:
          type: string
          description: "The unique identifier for the export file configuration. If not provided, a new configuration will be created."
        delimiter:
          type: string
          description: "The delimiter used in the export file (e.g., comma, semicolon)."
          example: ","
        exportFileformat:
          type: string
          description: The format of the export file (e.g., Standard).
          example: "Standard"
        timezone:
          type: string
          description: The timezone to be used for the export file.
          example: "UTC"

    ExportFileConfigurationResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully updated device location."
              minimum: 1
              maximum: 50
            exportFileConfigurationId:
              type: string
              description: "The unique identifier for the export file configuration."


# Get Alarms Response

    GetCompanyAlarmsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            companyId:
              type: string
              description: The company_id requested for alarms devices.
            devices:
              type: array
              description: Default sorting will be based on collectedTimestamp
              items:
                type: object
                properties:
                  deviceId:
                    type: string
                    description: "The device's unique id"
                    example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                  alarms:
                    type: array
                    items:
                      type: object
                      properties:
                        collectedTimestamp:
                          type: string
                          description: Timestamp when the alarm was raised in the module.
                        alarmID:
                          type: string
                          description: Alarm ID.
                        alarmType:
                          type: string
                          description: Alarm Category.
                          enum:
                            - ModuleAlarms
                            - HostDeviceAlarms
                            - OtherAlarmType
                        alarmStatus:
                          type: string
                          description: Alarm Status.
                          enum:
                            - Active
                            - Reset
                          example: Active
                        alarmDescription:
                          type: string
                          description: Alarm description.
            pageSize:
              type: integer
              example: 15
              default: 15
              enum:
                - 15
                - 30
                - 50
              description: "Optional. The maximum of values to fetch. Will add a 'NextToken' key to fetch the next page. Defaults to 15"
            fetchLast:
              type: string
              example: True
              enum:
                - True
                - False
              description: Pass true if need to fetch the last page
            nextToken:
              type: string
              default: None
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: "A base64 encoded string to fetch the next page of the paginated result."
            previousToken:
              type: string
              default: None
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: "A base64 encoded string to fetch the previous page of the paginated result."
            fromDateTime:
              type: string
              example: "YYYY-MM-DDThh:mm:ss.SSSZ"
              default: None
              description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"
            toDateTime:
              type: string
              example: "YYYY-MM-DDThh:mm:ss.SSSZ"
              default: None
              description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"

    GetDeviceAlarmsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deviceId:
              type: string
              description: "The device's unique id"
              example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
            alarms:
              type: array
              description: Default sorting will be based on collectedTimestamp
              items:
                type: object
                properties:
                  collectedTimestamp:
                    type: string
                    description: Timestamp when the alarm was raised in the module.
                  alarmId:
                    type: string
                    description: Alarm ID.
                  alarmType:
                    type: string
                    description: Alarm type.
                    enum:
                      - ModuleAlarms
                      - HostDeviceAlarms
                      - OtherAlarmType
                  alarmCategory:
                    type: string
                    description: Alarm category.
                    enum:
                      - Error
                      - Alarm
                  alarmStatus:
                    type: string
                    description: Alarm Status.
                    enum:
                      - Active
                      - Reset
                  acknowledgedBy:
                    type: string
                    description: Email of the user.
                    example: john@doe.com
                  acknowledgedAt:
                    type: string
                    description: Timestamp when the alarm was acknowledged.
                    example: "2023-01-01T12:00:00Z"
            pageSize:
              type: integer
              example: 15
              default: 15
              enum:
                - 15
                - 30
                - 50
              description: "Optional. The maximum of values to fetch. Will add a 'NextToken' key to fetch the next page. Defaults to 15"
            totalAlarmCount:
              type: integer
              description: The total number of alarms.
              example: 550
            nextToken:
              type: string
              default: None
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: "A base64 encoded string to fetch the next page of the paginated result."
            previousToken:
              type: string
              default: None
              example: "eyabcdefgegOIjlwPIJmqmlqjzIOPJkLQjfd"
              description: "A base64 encoded string to fetch the previous page of the paginated result."
            fromDateTime:
              type: string
              example: "YYYY-MM-DDThh:mm:ss.SSSZ"
              default: None
              description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"
            toDateTime:
              type: string
              example: "YYYY-MM-DDThh:mm:ss.SSSZ"
              default: None
              description: "The date-time in the UTC format, user may pass just YYYY or YYYY-MM or YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.SSSZ"


# Device Parameter read write models
    
    DeviceParameterReadRequest:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: array
          minimum: 1
          maximum: 5
          items:
            type: string  
            minimum: 1
            maximum: 32
            example: "parameter_id"   
            description: "parameter unique id , Note:- Parameter details like parameter ID could be fetched using fetch all paramter API."
          example: ["parameter1_id","parameter2_id"] 

    DeviceParameterReadResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              deviceId:
                type: string
                description: "The device's unique id"
                example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
                description: "The type of the device"
              parameterId:
                type: string
                example: "phys_software_rev"
                description: "parameter unique id"
              status:
                type: string
                enum:
                  - Accepted
                  - InProgress
                example: "Accepted"
                description: On First hit status will be "Accepted" but if read is requested for a parameter for which previous read request is still pending then value of Status will be "InProgress"
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: "unique error id - uuid"
                example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
              code:
                type: string
                description: "unique error code"
                example: "FWENQ-0x00000001"
              title:
                type: string
                description: "Error title"
                example: "Bad Request"
              status:
                type: number
                description: "HTTP Status code"
                example: "400"
              details:
                type: string
                description: "error message"
                example: "Invalid Serial number"
              meta:
                type: object
                properties:
                  deviceId:
                    type: string
                    description: "The device's unique id"
                    example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                  deviceType:
                    type: string
                    enum:
                      - "Mag8000-4G"
                      - "Mag8000-LoRa"
                      - "CC220"
                      - "MS200"
                      - "IoTRadar"
                      - "Mag8000-4G-Flex"
                      - "Mag8000-LoRaGateway"
                    example: "Mag8000-4G"
                    description: "The type of the device"
                  parameterId:
                    type: string
                    example: "phys_software_rev"
                    description: "parameter unique id"
              correlationId:
                type: string
                description: "transaction unique id"
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"


    DeviceParameterWriteRequest:
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: array
          minimum: 1
          maximum: 5
          items:
            type: object  
            required:
              - parameterId
              - parameterValue
            properties:
              parameterId:
                type: string
                minimum: 1
                maximum: 32
                example: "phys_software_rev"
                description: "parameter unique id, Note:- Parameter details like parameter ID could be fetched using fetch all paramter API."
              parameterValue:
                type: string
                minimum: 1
                maximum: 32
                example: "01.00.02-52"
                description: "parameter value"


    DeviceParameterWriteResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              deviceId:
                type: string
                description: "The device's unique id"
                example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
              deviceType:
                type: string
                enum:
                  - "Mag8000-4G"
                  - "Mag8000-LoRa"
                  - "CC220"
                  - "MS200"
                  - "IoTRadar"
                  - "Mag8000-4G-Flex"
                  - "Mag8000-LoRaGateway"
                example: "Mag8000-4G"
                description: "The type of the device"
              parameterId:
                type: string
                example: "phys_software_rev"
                description: "parameter unique id"
              parameterValue:
                type: string
                example: "01.00.02-52"
                description: "parameter value"
              status:
                type: string
                enum:
                  - Accepted
                  - InProgress
                example: "Accepted"
                description: On First hit status will be "Accepted" but if read is requested for a parameter for which previous read request is still pending then value of Status will be "InProgress"
        errors:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: "unique error id - uuid"
                example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
              code:
                type: string
                description: "unique error code"
                example: "FWENQ-0x00000001"
              title:
                type: string
                description: "Error title"
                example: "Bad Request"
              status:
                type: number
                description: "HTTP Status code"
                example: "400"
              details:
                type: string
                description: "error message"
                example: "Invalid Serial number"
              meta:
                type: object
                properties:
                  deviceId:
                    type: string
                    description: "The device's unique id"
                    example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                  deviceType:
                    type: string
                    enum:
                      - "Mag8000-4G"
                      - "Mag8000-LoRa"
                      - "CC220"
                      - "MS200"
                      - "IoTRadar"
                      - "Mag8000-4G-Flex"
                      - "Mag8000-LoRaGateway"
                    example: "Mag8000-4G"
                    description: "The type of the device"
                  parameterId:
                    type: string
                    example: "phys_software_rev"
                    description: "parameter unique id"
                  parameterValue:
                    type: string
                    example: "01.00.02-52"
                    description: "parameter value"
              correlationId:
                type: string
                description: "transaction unique id"
                example: "1-66f3a9dc-4924ac09759b99e51766d14d"


    GetAllDeviceParametersResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deviceId:
              type: string
              description: "The device's unique id"
              example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
            parameters:
              type: array
              items:
                type: object
                properties:
                  parameterId:
                    type: string
                    example: "phys_software_rev"
                    description: "parameter unique id"
                  values:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: "ParameterName"
                        value:
                          type: string
                          example: "param_name"

# Update Device Location Request and Response
    UpdateDeviceRequest:
      type: object
      required:
        - latitude
        - longitude
        - deviceLocation
      properties:
        latitude:
          type: number
          format: float
          example: 37.7749
          minimum: -90
          maximum: 90
          description: Latitude of the location
        longitude:
          type: number
          format: float
          example: -122.4194
          minimum: -180
          maximum: 180
          description: Longitude of the location
        deviceLocation:
          type: string
          example: "San Francisco, CA"
          description: Textual description of the device location
          minimum: 3
          maximum: 255
        

    UpdateDeviceResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Successfully updated device location."
              minimum: 1
              maximum: 50
            deviceId:
              type: string
              example: "1234-f44j-44f4-44f"
              description:  "UUID of device record"
              minimum: 1
              maximum: 64

# Device KPI Response

    DeviceKPIResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            totalDeviceCount:
              type: integer
              description: The total number of devices.
              example: 550
            onlineDeviceCount:
              type: integer
              description: The number of devices that are online.
              example: 400
            offlineDeviceCount:
              type: integer
              description: The number of devices that are offline.
              example: 150
            alarmInDeviceCount:
              type: integer
              description: The number of devices that have triggered alarms.
              example: 200
            errorInDeviceCount:
              type: integer
              description: The number of devices that are offline.
              example: 250

    GetDeviceSubscriptionsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            devices:
              type: array
              items:
                type: string
                example: "device001"
            page:
              type: integer
              example: 1
            pageSize:
              type: integer
              example: 10
            totalItems:
              type: integer
              example: 100
            totalPages:
              type: integer
              example: 10 

    GetAlarmSubscriptionsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            alarm_subscription_id:
              type: string
              example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            alarms:
              type: array
              items:
                type: string
                example: "al1"
    
    CreateAlarmSubscriptionRequest:
      type: object
      properties:
        userId:
          type: string
          description: The ID of the user to subscribe.
          example: "user123"
        alarms:
          type: array
          items:
            type: string
            example: "al1"
    
    CreateAlarmSubscriptionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            alarmSubscriptionId:
              type: string
              description: The ID of the subscription.
              example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            status:
              type: string
              description: Status of the subscription creation.
              example: "201 Created"
            message:
              type: string
              description: Message about the subscription creation.
              example: "Subscription created successfully."
          example:
            subscriptionId: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            status: "201 Created"
            message: "Subscription created successfully."


    UpdateAlarmSubscriptionRequest:
      type: object
      properties:
        alarmSubscriptionId:
          type: string
          description: The alarmSubscriptionId of the existing subcription.
          example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
        alarms:
          type: array
          items:
            type: string
            example: "al1"

    UpdateAlarmSubscriptionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            alarmSubscriptionId:
              type: string
              description: The ID of the subscription.
              example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            status:
              type: string
              description: Status of the subscription creation.
              example: "201 Created"
            message:
              type: string
              description: Message about the subscription creation.
              example: "Subscription updated successfully."
          example:
            subscriptionId: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            status: "200 Ok"
            message: "Subscription updated successfully."

    CreateDeviceSubscriptionRequest:
      type: object
      properties:
        userId:
          type: string
          description: The ID of the user to subscribe.
          example: "f5ef2e1-098c-4541-8473-4a0a6d7da922"
        deviceId:
          type: string
          description: The ID of the device to subscribe.
          example: "mgb7f2e1-098c-4541-8473-4a0a6d7da922"
    
    CreateDeviceSubscriptionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deviceSubscriptionId:
              type: string
              description: The ID of the subscription.
              example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            status:
              type: string
              description: Status of the subscription creation.
              example: "201 Created"
            message:
              type: string
              description: Message about the subscription creation.
              example: "Subscription created successfully."
          example:
            subscriptionId: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
            status: "201 Created"
            message: "Subscription created successfully."

    DeleteSubscriptionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message:
              type: string
              example: "Subscription deleted successfully."



    # CreateAlarmMetadataRequest:
    #   type: object
    #   properties:
    #     deviceType:
    #       type: string
    #       maxLength: 64
    #       description: Type of device that can trigger this alarm.
    #     alarmDescription:
    #       type: string
    #       maxLength: 255
    #       description: Description of the alarm.
    #     alarmType:
    #       type: string
    #       maxLength: 50
    #       description: Type of alarm.
    #     alarmNumber:
    #       type: string
    #       maxLength: 50
    #       description: Alarm number or code.
    #     severity:
    #       type: integer
    #       format: int32
    #       minimum: 0
    #       maximum: 65535
    #       description: Severity level of the alarm.
    #   required:
    #     - deviceType

    # CreateAlarmMetadataResponse:
    #   type: object
    #   properties:
    #     data:
    #       type: object
    #       properties:
    #         alarmMetadataId:
    #           type: string
    #           format: uuid
    #           description: Unique identifier for the created alarm metadata.
    #           example: "1-66f3a9dc-4924ac09759b99e51766d14d"
    #         deviceType:
    #           type: string
    #           maxLength: 64
    #           description: Type of device that can trigger this alarm.
    #           example: "Mag8000-4G"
    #         alarmDescription:
    #           type: string
    #           maxLength: 255
    #           description: Description of the alarm.
    #           example: "Battery low warning"
    #         alarmType:
    #           type: string
    #           maxLength: 50
    #           description: Type of alarm.
    #           example: "ModuleAlarms"
    #         alarmNumber:
    #           type: string
    #           maxLength: 50
    #           description: Alarm number or code.
    #           example: "ALM001"
    #         severity:
    #           type: integer
    #           format: int32
    #           minimum: 0
    #           maximum: 65535
    #           description: Severity level of the alarm.
    #           example: 2
    
    # UpdateAlarmMetadataRequest:
    #     type: object
    #     properties:
    #         alarmMetadataId:
    #           type: string
    #           format: uuid
    #           description: Unique identifier for the alarm metadata.
    #         deviceType:
    #           type: string
    #           maxLength: 64
    #           description: Type of device that can trigger this alarm.
    #         alarmDescription:
    #           type: string
    #           maxLength: 255
    #           description: Description of the alarm.
    #         alarmType:
    #           type: string
    #           maxLength: 50
    #           description: Type of alarm.
    #         alarmNumber:
    #           type: string
    #           maxLength: 50
    #           description: Alarm number or code.
    #         severity:
    #           type: integer
    #           format: int32
    #           minimum: 0
    #           maximum: 65535
    #           description: Severity level of the alarm.
    #     required:
    #       - alarmMetadataId

    # UpdateAlarmMetadataResponse:
    #   type: object
    #   properties:
    #     data:
    #       type: object
    #       properties:
    #         message:
    #           type: string
    #           example: "Successfully updated Alarm metadata details."
    #         alarmMetadataId:
    #           type: string
    #           example: "1234-f44j-44f4-44f"
    #           description:  "UUID of Alarm metadata"

    GetAlarmMetadataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            alarmMetadata:
              type: array
              items:
                type: object
                properties:
                  alarmMetadataId:
                    type: string
                    format: uuid
                    description: Unique identifier for the created alarm metadata.
                    example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
                  deviceType:
                    type: string
                    maxLength: 64
                    description: Type of device that can trigger this alarm.
                    example: "Mag8000-4G"
                  alarmDescription:
                    type: string
                    maxLength: 255
                    description: Description of the alarm.
                    example: "Battery low warning"
                  alarmType:
                    type: string
                    maxLength: 50
                    description: Type of alarm.
                    example: "ModuleAlarms"
                  alarmCategory:
                    type: string
                    description: Category of alarm [Error, Alarm].
                    enum:
                      - error
                      - alarm
                  alarmNumber:
                    type: string
                    maxLength: 50
                    description: Alarm number or code.
                    example: "ALM001"
                  severity:
                    type: integer
                    format: int32
                    minimum: 0
                    maximum: 65535
                    description: Severity level of the alarm.
                    example: 2

    # DeleteAlarmMetadataResponse:
    #   type: object
    #   properties:
    #     data:
    #       type: object
    #       properties:
    #         message:
    #           type: string
    #           example: "Alarm metadata deleted successfully."
    #         alarmMetadataId:
    #           type: string
    #           example: "3c987a69-d7cc-49ad-ae91-c94003b78f16"
    #           description:  "UUID of Alarm metadata"
            
# Error Responses 

  responses:
    400Error:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: "unique error id - uuid"
                      example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
                    code:
                      type: string
                      description: "unique error code"
                      example: "FWENQ-0x00000001"
                    title:
                      type: string
                      description: "Error title"
                      example: "Bad Request"
                    status:
                      type: number
                      description: "HTTP Status code"
                      example: "400"
                    details:
                      type: string
                      description: "error message"
                      example: "Invalid Serial number"
                    meta:
                      type: object
                    correlationId:
                      type: string
                      description: "transaction unique id"
                      example: "1-66f3a9dc-4924ac09759b99e51766d14d"

    500Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: "unique error id - uuid"
                      example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
                    code:
                      type: string
                      description: "unique error code"
                      example: "FWENQ-0x00000001"
                    title:
                      type: string
                      description: "Error title"
                      example: "Internal Server Error"
                    status:
                      type: number
                      description: "HTTP Status code"
                      example: "500"
                    details:
                      type: string
                      description: "error message"
                      example: "Internal Server Error"
                    meta:
                      type: object
                    correlationId:
                      type: string
                      description: "transaction unique id"
                      example: "1-66f3a9dc-4924ac09759b99e51766d14d"

    405Error:
      description: Invalid Method
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: "unique error id - uuid"
                      example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
                    code:
                      type: string
                      description: "unique error code"
                      example: "FWENQ-0x00000001"
                    title:
                      type: string
                      description: "Error title"
                      example: "Invalid Method"
                    status:
                      type: number
                      description: "HTTP Status code"
                      example: "405"
                    details:
                      type: string
                      description: "error message"
                      example: "POST id Invalid Method"
                    meta:
                      type: object
                    correlationId:
                      type: string
                      description: "transaction unique id"
                      example: "1-66f3a9dc-4924ac09759b99e51766d14d"

    401Error:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: "unique error id - uuid"
                      example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
                    code:
                      type: string
                      description: "unique error code"
                      example: "FWENQ-0x00000001"
                    title:
                      type: string
                      description: "Error title"
                      example: "Unauthorized"
                    status:
                      type: number
                      description: "HTTP Status code"
                      example: "401"
                    details:
                      type: string
                      description: "error message"
                      example: "Unauthorized user credentials"
                    meta:
                      type: object
                    correlationId:
                      type: string
                      description: "transaction unique id"
                      example: "1-66f3a9dc-4924ac09759b99e51766d14d"

    403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: "unique error id - uuid"
                      example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
                    code:
                      type: string
                      description: "unique error code"
                      example: "FWENQ-0x00000001"
                    title:
                      type: string
                      description: "Error title"
                      example: "Forbidden"
                    status:
                      type: number
                      description: "HTTP Status code"
                      example: "403"
                    details:
                      type: string
                      description: "error message"
                      example: "Access is Forbidden"
                    meta:
                      type: object
                    correlationId:
                      type: string
                      description: "transaction unique id"
                      example: "1-66f3a9dc-4924ac09759b99e51766d14d"

    404Error:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: "unique error id - uuid"
                      example: "f8b7f2e1-098c-4541-8473-4a0a6d7dac91"
                    code:
                      type: string
                      description: "unique error code"
                      example: "FWENQ-0x00000001"
                    title:
                      type: string
                      description: "Error title"
                      example: "Not Found"
                    status:
                      type: number
                      description: "HTTP Status code"
                      example: "404"
                    details:
                      type: string
                      description: "error message"
                      example: "Requested resource is not found"
                    meta:
                      type: object
                    correlationId:
                      type: string
                      description: "transaction unique id"
                      example: "1-66f3a9dc-4924ac09759b99e51766d14d"
