openapi: 3.2.0
info:
  version: 0.7.0
  title: Aeris IoT Watchtower™ Device Groups API
  description: '## Introduction


    The Aeris IoT Watchtower™ API provides access to resources such as real-time events, aggregated events, risk assessment reports, and device group operations.'
  termsOfService: https://www.aeris.com/services-terms-of-use/
  contact:
    email: support@aeris.net
    url: https://www.aeris.com/support/
  license:
    name: Aeris License
    url: https://www.aeris.com/services-terms-of-use/
  x-audience: external-public
servers:
- url: https://watchtower-api-prd.aeriscloud.com
security:
- oAuth2ClientCredentials: []
tags:
- name: Device Groups
  description: Endpoints for Device Groups
paths:
  /watchtower/v1/device-groups:
    post:
      summary: Create a new device group
      operationId: createDeviceGroup
      tags:
      - Device Groups
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupCreateRequest'
      responses:
        '201':
          description: Device group created successfully
          content:
            application/json:
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/device-groups/search:
    post:
      summary: Get device groups
      tags:
      - Device Groups
      operationId: getDeviceGroups
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeviceGroupTable'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '413':
          $ref: '#/components/responses/413'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/device-groups/{deviceGroupId}:
    get:
      summary: Get device group details
      tags:
      - Device Groups
      operationId: getDeviceGroup
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/deviceGroupId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceGroup'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    put:
      summary: Update an existing device group
      operationId: updateDeviceGroup
      tags:
      - Device Groups
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/deviceGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupUpdateRequest'
      responses:
        '204':
          description: No content, the resource was successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      summary: Delete a new device group
      operationId: deleteDeviceGroup
      tags:
      - Device Groups
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/deviceGroupId'
      responses:
        '204':
          description: No content, the resource was successfully deleted.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/device-groups/export:
    post:
      summary: Get Device Groups exported as CSV
      tags:
      - Device Groups
      operationId: exportDeviceGroups
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledReport'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/device-groups/{deviceGroupId}/devices/export:
    post:
      summary: Get Device Group Devices exported as CSV
      tags:
      - Device Groups
      operationId: exportDeviceGroupDevices
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/deviceGroupId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledReport'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    startTime:
      name: startTime
      in: query
      required: true
      description: The start timestamp. (inclusive)
      example: '2021-07-01T06:30:00Z'
      schema:
        $ref: '#/components/schemas/dateTime'
    endTime:
      name: endTime
      in: query
      required: true
      description: The end timestamp. (exclusive)
      example: '2021-07-05T06:30:00Z'
      schema:
        $ref: '#/components/schemas/dateTime'
    accountId:
      name: X-Watchtower-Account-Id
      in: header
      description: Account Id
      required: true
      schema:
        $ref: '#/components/schemas/accountId'
      example: 1002000010
    offset:
      name: offset
      in: query
      description: The position in pagination. Specifies the starting row offset into the result set returned. For example, if the page size (limit) is 10, then to select the second page, pass the offset as 10 to retrieve items 11 to 20.<br><br> Search parameters must be consistent across pages.
      schema:
        $ref: '#/components/schemas/offset'
    deviceGroupId:
      name: deviceGroupId
      in: path
      required: true
      description: The ID of the device group
      schema:
        type: integer
    authorization:
      name: Authorization
      in: header
      description: Bearer Token for authentication
      required: true
      schema:
        type: string
        pattern: ^Bearer [A-Za-z0-9-._~+/]+=*$
      example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...
    limit:
      name: limit
      in: query
      description: The number of items to retrieve per page (10000 max).
      schema:
        $ref: '#/components/schemas/limit'
  schemas:
    DeviceGroupBase:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        colorCode:
          type: string
        deviceAssigningType:
          $ref: '#/components/schemas/DeviceGroupAssigningType'
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/DeviceCustomField'
        devices:
          type: array
          description: Information about devices. Fill if deviceAssigningType = MANUALLY, empty otherwise
          items:
            $ref: '#/components/schemas/Device'
        tacCodes:
          type: array
          items:
            $ref: '#/components/schemas/DeviceTACCodeInfo'
        totalDevices:
          type: integer
        createdBy:
          type: string
        createdTime:
          type: string
          format: date-time
        updatedBy:
          type: string
        updatedTime:
          type: string
          format: date-time
        ranking:
          type: integer
        deviceGroupType:
          $ref: '#/components/schemas/DeviceGroupType'
        servicePlan:
          type: string
          deprecated: true
          description: Deprecated. Use servicePlans.
        servicePlans:
          type: array
          items:
            type: string
        enforcementRules:
          type: array
          items:
            $ref: '#/components/schemas/EnforcementRuleBase'
        locationListIds:
          type: array
          items:
            type: integer
            format: int64
    total:
      type: integer
      format: int64
      description: Total number of items available.
      example: 1
      minimum: 0
    offset:
      description: Position in pagination.
      type: integer
      format: int32
      default: 0
      minimum: 0
    limit:
      type: integer
      format: int32
      description: Number of items to retrieve (10000 max).
      minimum: 1
      maximum: 10000
      default: 20
    Device:
      type: object
      required:
      - iccid
      - imsi
      properties:
        iccid:
          type: string
          description: iccid of device
          maxLength: 50
        imsi:
          type: string
          description: imsi of device
          maxLength: 50
    accountId:
      description: Account Id.
      type: integer
      format: int32
      example: 10407
      minimum: 0
    DeviceCustomField:
      type: object
      description: Information about custom fields. Fill if deviceAssigningType = AUTO_BY_CUSTOM_FIELDS, empty otherwise
      required:
      - customFieldId
      - customFieldValue
      properties:
        customFieldId:
          type: integer
          format: int64
          description: custom field id of group
        customFieldValue:
          type: string
          description: custom field value of group
          maxLength: 256
    DeviceGroupCreateRequest:
      allOf:
      - $ref: '#/components/schemas/DeviceGroupResourceBase'
      - type: object
        properties:
          deviceGroupType:
            $ref: '#/components/schemas/DeviceGroupType'
    DeviceTACCodeInfo:
      type: object
      properties:
        tac:
          type: string
        type:
          type: string
        brand:
          type: string
        model:
          type: string
        totalDevices:
          type: integer
        deviceGroups:
          type: array
          items:
            $ref: '#/components/schemas/DeviceGroupInfo'
    PagedDeviceGroupTable:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/DeviceGroup'
    DeviceGroupQueryRequest:
      type: object
      description: Search for name, assign type and created time range (set to null if don't want to filter)
      properties:
        name:
          type: string
          maxLength: 1024
        deviceAssigningType:
          type: array
          items:
            $ref: '#/components/schemas/DeviceGroupAssigningType'
        deviceGroupType:
          type: array
          items:
            $ref: '#/components/schemas/DeviceGroupType'
        enforcementRuleId:
          type: array
          items:
            type: integer
        enforcementRuleStatus:
          type: array
          items:
            type: string
        rankingMin:
          type: integer
        rankingMax:
          type: integer
        totalMin:
          type: integer
        totalMax:
          type: integer
        tac:
          type: array
          items:
            type: string
        brand:
          type: array
          items:
            type: string
        model:
          type: array
          items:
            type: string
        type:
          type: array
          items:
            type: string
        enforcementRuleApn:
          type: array
          items:
            type: string
        enforcementRuleApnNot:
          type: array
          items:
            type: string
        isCountingActiveOnly:
          type: boolean
          default: true
    DeviceGroupResourceBase:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        deviceAssigningType:
          $ref: '#/components/schemas/DeviceGroupAssigningType'
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/DeviceCustomField'
          description: Information about custom fields. Fill if deviceAssigningType = AUTO_BY_CUSTOM_FIELDS, empty otherwise
        devices:
          type: array
          description: Information about devices. Fill if deviceAssigningType = MANUALLY, empty otherwise
          items:
            $ref: '#/components/schemas/Device'
        tacCodes:
          type: array
          items:
            type: string
          description: Information about tac codes. Fill if deviceAssigningType = AUTO_BY_TAC_CODES, empty otherwise
        servicePlan:
          type: string
          deprecated: true
          description: Deprecated. Use servicePlans.
        servicePlans:
          type: array
          items:
            type: string
        ranking:
          type: integer
    Error:
      type: object
      properties:
        code:
          type: integer
          description: HTTP code
          example: 500
        message:
          type: string
          description: Error message
          example: An error encountered in processing the request
        timestamp:
          type: string
          description: ISO DateTime
          example: '2025-06-02 09:01:53.678'
        path:
          type: string
          description: Endpoint path at which the error occured
          example: /watchtower/v1/events
        traceId:
          type: string
          description: Trace Id
          example: ed81f29f-ea9b-4099-aa00-f8ed40b7a567
    DeviceGroupType:
      type: string
      enum:
      - REPORTING
      - ENFORCEMENT
    DeviceGroupAssigningType:
      type: string
      description: assign type
      enum:
      - AUTO_BY_TAC_CODES
      - AUTO_BY_CUSTOM_FIELDS
      - MANUALLY
      - AUTO_BY_SERVICE_PLAN
      example: AUTO_BY_TAC_CODES
    DeviceGroupUpdateRequest:
      allOf:
      - $ref: '#/components/schemas/DeviceGroupResourceBase'
    dateTime:
      description: ISO 8601 date time
      type: string
      format: date-time
      example: '2021-07-04T17:36:47Z'
    Pagination:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/total'
        offset:
          $ref: '#/components/schemas/offset'
        limit:
          $ref: '#/components/schemas/limit'
    DeviceGroup:
      allOf:
      - type: object
        properties:
          id:
            type: integer
      - $ref: '#/components/schemas/DeviceGroupBase'
    ScheduledReport:
      type: object
      properties:
        reportId:
          description: Report Id
          type: string
          example: 7ae9e22d-8ad4-4a69-950a-6b13d75f0c74
        status:
          $ref: '#/components/schemas/ReportStatus'
        statusEndpoint:
          description: Report Status URL
          type: string
          example: /watchtower/v1/scheduled-reports/7ae9e22d-8ad4-4a69-950a-6b13d75f0c74
    ReportStatus:
      description: Report status
      type: string
      example: Processing
      enum:
      - Success
      - Processing
      - Error
      - NotStarted
    enforcementRuleId:
      description: Enforcement Rule identifier
      type: integer
      format: int64
      example: 5102010
    EnforcementRuleBase:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/enforcementRuleId'
        name:
          type: string
        status:
          type: string
        apn:
          type: string
    DeviceGroupInfo:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        colorCode:
          type: string
        deviceGroupType:
          type: string
  responses:
    '429':
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 429
            message: 'Rate Limit Exceeded (XX) for clientId: XXXXXX. Please retry after XXX seconds'
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '401':
      description: Not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '403':
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '400':
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '404':
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not found
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '413':
      description: Requested data too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 413
            message: Requested data too large. Please use /watchtower/v1/.../export for requesting larger amounts of data
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: This API uses OAuth 2 with the Client Credentials flow.
      flows:
        clientCredentials:
          tokenUrl: /watchtower/v1/auth/token
          scopes: {}