openapi: 3.2.0
info:
  version: 0.7.0
  title: Aeris IoT Watchtower™ TAC Codes 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: TAC Codes
paths:
  /watchtower/v1/tac-codes/search:
    post:
      summary: Search TAC Codes
      description: 'Returns a paginated list of TAC codes (Type Allocation Codes) observed across all devices in the account, including the device type, brand, model, and the total number of devices sharing that TAC.

        Sort by `totalDevices:DESC` (default) or any other response field in `asc`/`desc` order.'
      operationId: searchTACCodes
      tags:
      - TAC Codes
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/sort'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TACCodeSearchFilter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedTACCodeList'
        '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/tac-codes/summary:
    get:
      summary: Get TAC Codes Metrics
      description: 'Returns a full summary of TAC code distributions across all devices in the account: device type breakdown (`summaryOfTypes`), manufacturer brand breakdown (`summaryOfBrands`), and model breakdown (`summaryOfModels`), plus the total device count with a recognised TAC (`totalTacCodeDevices`).

        No pagination — returns the complete result set in a single response.'
      operationId: getTACCodesSummary
      tags:
      - TAC Codes
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TACCodeMetrics'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  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
    '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
  schemas:
    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
    accountId:
      description: Account Id.
      type: integer
      format: int32
      example: 10407
      minimum: 0
    TACCodeSummaryEntry:
      type: object
      description: A name/count pair representing one category in a TAC code metric summary.
      properties:
        name:
          type: string
          description: Category label (device type, brand name, or model name).
          example: Modem
        total:
          type: integer
          description: Number of devices in this category.
          example: 405
    TACCodeSearchFilter:
      type: object
      description: Optional filter body for searching TAC codes. All filters are optional; omit the body or send `{}` to retrieve all TAC codes for the account.
      properties:
        tac:
          type: array
          description: Filter by one or more exact TAC codes.
          items:
            type: string
          example:
          - '86471806'
          - '35691411'
        type:
          type: array
          description: Filter by device type (case-insensitive).
          items:
            type: string
          example:
          - Modem
          - IoT Device
        brand:
          type: array
          description: Filter by device brand/manufacturer (case-insensitive).
          items:
            type: string
          example:
          - Quectel
          - Fibocom
        model:
          type: array
          description: Filter by device model (case-insensitive).
          items:
            type: string
          example:
          - EC21
          - MA510-GL
    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
    TACCodeMetrics:
      type: object
      description: Full TAC code distribution summary for the account.
      properties:
        totalTacCodeDevices:
          type: integer
          description: Total number of devices with a recognised TAC in the account.
          example: 478
        summaryOfTypes:
          type: array
          description: Distribution of devices by device type (e.g. Modem, IoT Device).
          items:
            $ref: '#/components/schemas/TACCodeSummaryEntry'
        summaryOfBrands:
          type: array
          description: Distribution of devices by manufacturer brand.
          items:
            $ref: '#/components/schemas/TACCodeSummaryEntry'
        summaryOfModels:
          type: array
          description: Distribution of devices by model name.
          items:
            $ref: '#/components/schemas/TACCodeSummaryEntry'
    Pagination:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/total'
        offset:
          $ref: '#/components/schemas/offset'
        limit:
          $ref: '#/components/schemas/limit'
    PagedTACCodeList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            description: List of TAC code entries observed in the account.
            items:
              $ref: '#/components/schemas/TACCodeEntry'
    TACCodeEntry:
      type: object
      description: TAC code entry with device type metadata and total device count.
      properties:
        tac:
          type: string
          description: TAC (Type Allocation Code) — first 8 digits of the IMEI.
          example: '86471806'
        type:
          type: string
          description: Device category derived from the TAC.
          example: Modem
        brand:
          type: string
          description: Device manufacturer derived from the TAC.
          example: Fibocom
        model:
          type: string
          description: Device model derived from the TAC.
          example: MA510-GL
        totalDevices:
          type: integer
          description: Number of devices in the account that share this TAC.
          example: 113
  parameters:
    sort:
      name: sort
      in: query
      description: Use <b>sort=comma-separated-fields[:asc|desc]</b> to sort the result.
      example: deviceId,updateTime:desc
      schema:
        type: string
    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'
    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'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: This API uses OAuth 2 with the Client Credentials flow.
      flows:
        clientCredentials:
          tokenUrl: /watchtower/v1/auth/token
          scopes: {}