openapi: "3.0.3"

info:
  version: 0.7.0
  title: Aeris IoT Watchtower™ 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.

    The Watchtower API is based on the RESTful interface.

    This document covers the following topics:
    - Overview of the API
    - Detailed description of all available operations
    - Access, authentication, and rate limiting

    **Supported operations:**
    The Aeris IoT Watchtower API delivers security and management functionality based on your subscription package: 

    - Watchtower Analysis - this subscription package provides API access to the following operations: 
      - Events - Search, retrieve, update (single or bulk), export, metrics
      - Event configuration - Retrieve event configs, create/update/delete suppression configs
      - Event policies - Create, update, delete, search, view details, export (CSV), and search/export activity logs
      - Device - Retrieve the last IMEI changes for devices and the IMEI change history of a device
      - Device groups - Create, update, delete, search, retrieve details, export groups and group devices
      - IP flows/Blocked flows/Allowed traffic - Search and export blocked or allowed IP flows
      - Security reports - Export full PDF, retrieve summary, details, device location, endpoint location, appendix search/export
      - Scheduled reports - Retrieves the status and download link of a scheduled report
      - Activity logs - Retrieve activity logs for device groups, events, event configurations, event policies, and event policies activity logs
    
      Note: The WT Analysis permission is required to enable Watchtower Analysis API functionality. Watchtower Analysis only provides access to Reporting device groups.

    - Watchtower Protection - this subscription package provides API access to the following operations: 
      - Device groups - Create, update, delete, search, retrieve details, export groups and group devices
      - IP flows/Blocked flows/Allowed traffic - Search and export blocked or allowed IP flows
      - Scheduled reports - Retrieves the status and download link of a scheduled report
      - Activity logs - Retrieve activity logs for device groups, events, event configurations, location lists, and location lists activity logs
      - Applications - Create, update, delete, search, and view details of applications
      - Protection policies - Create, update, delete, search, and view details of allow or block protection policies
      - Enforcement rules - Create, update, delete, search, retrieve details, activate/deactivate enforcement rules
      - Location lists - Create, update, delete, search, suggest entries, and view details of location lists
    
      Note: The WT Protection permission is required to enable Watchtower Protection API functionality. Watchtower Protection only provides access to Enforcement device groups. The WT Complete permission provides access to both Reporting and Enforcement device groups.
    
    - Watchtower Complete - this subscription package provides API access to all capabilities from both the Analysis and Protection packages. 
    
    - Watchtower Monitoring - this subscription package does not include API access. 

    - Watchtower Control - this subscription package does not include API access. 

    ## Access, Authentication and Rate Limiting

    The Watchtower API uses Keycloak for authentication and authorization, with OAuth 2.0 Client Credentials Flow. 
    
    #### Obtaining Credentials
    
    The credentials are generated manually through a request procedure and transmitted securely to users.
    
    For Enterprise customers requesting Watchtower API access, an Aeris representative must open a Support ticket (CSP ticket) on behalf of the customer Administrator. The Support ticket must specify:
    - The Enterprise name.
    - The name and email address of the requestor (customer Administrator).
    - The list of Enterprises for which the request is being issued.

    Once the Support ticket is processed by Aeris, the credentials (`clientId` and `clientSecret`) will be securely provided to the requestor.

    Access to specific resources is determined by the roles associated with each `client_id`.

    #### Rate Limits 
    
    The API enforces a rate limit of 10 requests per minute per `client_id` and per `accountId`. Exceeding this limit returns a `429 Too Many Requests` error.

    #### Data Retrieval Limits 

    There is a maximum limit of 10,000 objects per request (downloading events, IP flows, or other resources). Exceeding this limit returns a `413 Request Entity Too Large` error and directs the user towards the relevant export endpoint.

    ## Scheduled Reports

    All `../export` endpoints start the generation of a Scheduled Report with a unique `reportId`. Use the `reportId` to query the dedicated endpoint for download. Reports are available for 10 minutes after generation. After they expire, a new request must be sent to the export endpoint to regenerate the report. 

    ## Activity Logs

    The Activity Logs API provides detailed records of all actions performed within the Watchtower platform. Queries to the `../export` endpoints for activity logs start the generation of an export file with a unique `reportId`. Use the `reportId` to query the dedicated endpoint for download. Reports are available for 10 minutes after generation. After they expire, a new request must be sent to the export endpoint to regenerate the report.

    ## Support

    Each API error response includes a `traceId`. When submitting an incident report to Aeris, include the associated `traceId` for troubleshooting.

  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

tags:
  - name: Token
    description: Endpoint to Acquire and Revoke Token
  - name: Events
    description: Endpoints for Awareness Security Events
  - name: Events Configuration
    description: Endpoints for configuring Security Events
  - name: Event Policies
    description: Endpoints for Awareness Event Policies
  - name: Devices
    description: >-
      Endpoints for Devices (IMEI changes) and per-device deep forensics analytics:
      Data Transactions, Data Volume, DNS Queries, Destination Endpoints, IP Flow Metrics.
  - name: Device Groups
    description: Endpoints for Device Groups
  - name: Flows
    description: Endpoints for flows - IP flows/Blocked flows/Allowed traffic
  - name: Security Report
    description: Endpoints for Security Reports
  - name: Scheduled Reports
    description: Endpoints for downloading Scheduled Reports
  - name: Activity Logs
    description: Endpoints for Activity Logs
  - name: Applications
    description: Endpoints for Enforcement Applications
  - name: Protection Policies
    description: Endpoints for Enforcement Protection Policies
  - name: Enforcement Rules
    description: Endpoints for Enforcement Rules
  - name: Rate Limiters
    description: Endpoints for Rate Limiters
  - name: Location Lists
    description: Endpoints for Location Lists
  - name: Gateway
    description: Watchtower Configuration APIs for Gateway management

security:
  - oAuth2ClientCredentials: [ ]

servers:
  - url: https://watchtower-api-prd.aeriscloud.com

paths:

  ########################## Token ################################################
  /watchtower/v1/auth/token:
    post:
      tags:
        - Token
      summary: Acquire Access token
      description: Endpoint to obtain an access token using Client Credentials flow
      operationId: getToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum: [ client_credentials ]
                  default: client_credentials
                client_id:
                  type: string
                  example: "operator1.enterprise1.application1"
                client_secret:
                  type: string
                  format: password
                  example: "tg69jPfKPtBEMzoPP1gNfI2HrCOZylpO"
      responses:
        '200':
          description: Successful token acquisition
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ..."
                  expires_in:
                    type: integer
                    example: 35998
                  refresh_expires_in:
                    type: integer
                    example: 0
                  token_type:
                    type: string
                    example: "Bearer"
                  not-before-policy:
                    type: integer
                    example: 0
                  scope:
                    type: string
                    example: "profile email"
                  authorized_account_ids:
                    type: array
                    items:
                      type: integer
                    example: [ 100000001, 100000002, 100000003 ]
                  authorized_account_id_pattern:
                    type: string
                    description: >-
                      Wildcard pattern for CSP Partner Admin credentials.
                      Present only for wildcard credentials; authorized_account_ids is absent in this case.
                    example: "020*"
        '400':
          description: "Missing required parameter: ..."
        '401':
          description: Invalid client credentials

  /watchtower/v1/auth/accounts:
    get:
      tags:
        - Token
      summary: Resolve wildcard account pattern to paginated account list
      description: >-
        Returns a paginated list of managed enterprise accounts (ID and name) for the CSP
        identified by the X-Watchtower-Account-Id header. Requires a Bearer token
        with the authorized_account_id_pattern claim (wildcard credentials).
        By default, returns only direct managed accounts. Use includeSubAccounts=true
        to return the full hierarchy of managed accounts.
      operationId: getAuthorizedAccounts
      parameters:
        - $ref: '#/components/parameters/authorization'
        - name: X-Watchtower-Account-Id
          in: header
          description: CSP Partner Admin's own account ID
          required: true
          schema:
            type: integer
            format: int64
          example: 10200000
        - name: limit
          in: query
          description: Number of results per page
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 500
        - name: offset
          in: query
          description: Zero-based offset for pagination
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: sort
          in: query
          description: >-
            Sort field and direction. Format: field,direction.
            Allowed fields: accountId, accountName. Directions: asc, desc.
          schema:
            type: string
            default: "accountId,asc"
          example: "accountName,desc"
        - name: includeSubAccounts
          in: query
          description: >-
            When false (default), returns only direct managed accounts.
            When true, returns the full hierarchy of managed accounts.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Paginated list of managed enterprise accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizedAccountsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'


  ########################## Generic ##############################################
  /watchtower/v1/scheduled-reports/{reportId}:
    get:
      summary: Get Report Status
      description: Returns the status of the scheduled report, and the download link if the report is ready
      operationId: getScheduledReport
      tags:
        - Scheduled Reports
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/reportId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledReportStatus'
        '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'


  ########################## [Awareness] Events ###################################
  /watchtower/v1/events:
    put:
      summary: Update multiple Events
      description: |
        This endpoint allows to update the status of one or more Events.
      operationId: updateEvents
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
      tags:
        - Events
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsBulkUpdateRequest'
      responses:
        '200':
          description: 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'
  /watchtower/v1/events/search:
    post:
      summary: Search/Get Events
      description: This endpoint returns the list of Events.
      operationId: getEvents
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEventsTable'
        '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/events/{eventId}:
    get:
      summary: Get details of an Event
      description: This endpoint retrieves details about an Event.
      operationId: getEvent
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/eventId'
      tags:
        - Events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '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 a single Event (Lifecycle operation)
      description: >
        This endpoint allows to update the status of an Event and provide a comment.
      operationId: updateEvent
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/eventId'
      tags:
        - Events
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsUpdateRequest'
      responses:
        '200':
          description: 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'
  /watchtower/v1/events/export:
    post:
      summary: Export Events
      description: Use this endpoint to export the Events report as CSV.
      operationId: exportEvents
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/startTime'
        - $ref: '#/components/parameters/endTime'
        - $ref: '#/components/parameters/sort'
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsQueryRequest'
      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/events/metrics/search:
    post:
      summary: Get Events Metrics
      description: >
        This endpoint returns metrics about Events. Allows you to retrieve arbitrary metrics
        by supplying dimensions, metrics and filters.
      operationId: getEventsMetrics
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsMetricsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSummaryTable'
              example:
                total: 4
                limit: 10
                offset: 0
                schema:
                  fields:
                    - name: status
                      type: STRING
                    - name: cnt__event_id
                      type: INTEGER
                data:
                  - - "New"
                    - 15
                  - - "Saved For Review"
                    - 5
                  - - "Dismissed"
                    - 6
                  - - "Completed"
                    - 10
        '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'
  # Next release: Events: also Devices

  # Aggregated Events
  /watchtower/v1/aggregate-events/metrics/search:
    post:
      summary: Get Aggregated Events Metrics
      description: This endpoint returns metrics about Aggregates events.
      operationId: getAggregatedEventsMetrics
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregatedEventsQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSummaryTable'
              example:
                total: 4
                limit: 10
                offset: 0
                lastEvaluatedDate: "2025-10-10"
                schema:
                  fields:
                    - name: status
                      type: STRING
                    - name: cnt__event_id
                      type: INTEGER
                data:
                  - - "New"
                    - 15
                  - - "Saved For Review"
                    - 5
                  - - "Dismissed"
                    - 6
                  - - "Completed"
                    - 10
        '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'

  # Next release: Origin & Destination Matrix

  # Events suppression configs
  /watchtower/v1/events/configs:
    get:
      summary: Get Event Configs
      description: |
        This endpoint returns the list of Event configs.
      operationId: getEventConfigs
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
      tags:
        - Events Configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEventConfigsTable'
        '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/events/configs/{eventConfigId}/suppression-configs:
    post:
      summary: Create an Event suppression configuration
      description: |
        This endpoint allows to create a new Event suppression configuration.
      operationId: createEventSuppressionConfig
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/eventConfigId'
      tags:
        - Events Configuration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSuppressionConfigCreateRequest'
      responses:
        '201':
          description: Created.
        '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/events/configs/{eventConfigId}/suppression-configs/{suppressionConfigId}:
    get:
      summary: Get Event Suppression Configs
      description: |
        This endpoint returns detail of event suppression configs.
      operationId: getEventSuppressionConfigs
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/eventConfigId'
        - $ref: '#/components/parameters/suppressionConfigId'
      tags:
        - Events Configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSuppressionConfig'
        '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'
    put:
      summary: Update Event Suppression Configs
      description: |
        This endpoint update existing event suppression configs.
      operationId: updateEventSuppressionConfigs
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/eventConfigId'
        - $ref: '#/components/parameters/suppressionConfigId'
      tags:
        - Events Configuration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSuppressionConfigUpdateRequest'
      responses:
        '200':
          description: 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 Event Suppression Configs
      description: |
        This endpoint deletes existing event suppression configs.
      operationId: deleteEventSuppressionConfigs
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/eventConfigId'
        - $ref: '#/components/parameters/suppressionConfigId'
        - $ref: '#/components/parameters/undoDismissedEvents'
      tags:
        - Events Configuration
      responses:
        '200':
          description: 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'


  ########################## [Awareness] Event Policies ###########################
  /watchtower/v1/event-policies:
    post:
      summary: Create an Event Policy
      operationId: createEventPolicy
      tags:
        - Event Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPolicyCreateRequest'
      responses:
        '201':
          description: Event policy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPolicyCreateResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          description: Conflict — an event policy with this name already exists for the account.
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/event-policies/search:
    post:
      summary: Search Event Policies
      operationId: searchEventPolicies
      tags:
        - Event Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPolicySearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEventPoliciesTable'
        '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/event-policies/{policyId}:
    get:
      summary: Get an Event Policy
      operationId: getEventPolicy
      tags:
        - Event Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/policyId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPolicyResponse'
        '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 Event Policy
      operationId: updateEventPolicy
      tags:
        - Event Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/policyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPolicyUpdateRequest'
      responses:
        '200':
          description: Successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          description: Conflict — an event policy with this name already exists for the account.
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      summary: Delete an Event Policy
      operationId: deleteEventPolicy
      tags:
        - Event Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/policyId'
      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'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/event-policies/export:
    post:
      summary: Export Event Policies
      description: Use this endpoint to export Event Policies as CSV.
      operationId: exportEventPolicies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
      tags:
        - Event Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPolicySearchRequest'
      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'


  ########################## [Awareness] SRS ######################################

  # IP Flows
  /watchtower/v1/ip-flows/search:
    post:
      summary: Search IP Flows (Account-level)
      description: >
        Retrieves structured IP flow records (BLOCKED or ALLOWED) across all devices in
        the account. Requires a `flowType` discriminator (`BLOCKED` or `ALLOWED`) in the
        request body to select the appropriate filter schema.

        **Distinct from `POST /watchtower/v1/devices/ip-flows/search`:**
        - This endpoint is **account-scoped** — it searches across all devices and returns
          structured `BLOCKED`/`ALLOWED` flow DTOs with enforcement policy context.
        - The device-scoped `/devices/ip-flows/search` is **device-scoped** via `iccid` and
          returns raw per-flow metric records (timing, data volume, source/destination detail)
          without enforcement context.
      operationId: getIPFlows
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/BlockedIPFlowsSearchRequest'
                - $ref: '#/components/schemas/AllowedIPFlowsSearchRequest'
              discriminator:
                propertyName: flowType
                mapping:
                  BLOCKED: '#/components/schemas/BlockedIPFlowsSearchRequest'
                  ALLOWED: '#/components/schemas/AllowedIPFlowsSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedFlows'
        '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/ip-flows/export:
    post:
      summary: API for exporting IP Flows
      description: This endpoint exports IP Flows as scheduled report
      operationId: exportIPFlows
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/startTime'
        - $ref: '#/components/parameters/endTime'
        - $ref: '#/components/parameters/sort'
      tags:
        - Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/BlockedIPFlowsSearchRequest'
                - $ref: '#/components/schemas/AllowedIPFlowsSearchRequest'
              discriminator:
                propertyName: flowType
                mapping:
                  BLOCKED: '#/components/schemas/BlockedIPFlowsSearchRequest'
                  ALLOWED: '#/components/schemas/AllowedIPFlowsSearchRequest'
      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'

  # Blocked Flows
  /watchtower/v1/blocked-flows/search:
    post:
      summary: API to get Blocked Flows
      description: This endpoint retrieves Blocked Flows
      operationId: searchBlockedFlows
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockedFlowsSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedBlockedFlows'
        '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/blocked-flows/export:
    post:
      summary: API to export Blocked Flows
      description: This endpoint exports Blocked Flows as CSV with Scheduled Report
      operationId: exportBlockedFlows
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockedFlowsSearchRequest'
      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'
        '413':
          $ref: '#/components/responses/413'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'

  # Allowed Traffic
  /watchtower/v1/allowed-traffic/search:
    post:
      summary: API to get Allowed Traffic
      description: This endpoint retrieves Allowed Traffic
      operationId: searchAllowedTraffic
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllowedTrafficSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAllowedTraffic'
        '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/allowed-traffic/export:
    post:
      summary: API to export Allowed Traffic
      description: This endpoint exports Allowed Traffic as CSV with Scheduled Report
      operationId: exportAllowedTraffic
      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'
        - $ref: '#/components/parameters/sort'
      tags:
        - Flows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllowedTrafficSearchRequest'
      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'
        '413':
          $ref: '#/components/responses/413'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'

  # Next release:
  # /v2.0/security/accounts/{accountId}/endpoints/search
  # /v2.0/security/accounts/{accountId}/endpoints/export
  # /v2.0/security/accounts/{accountId}/devices/search
  # /v2.0/security/accounts/{accountId}/devices/export

  # Device Changes
  /watchtower/v1/devices/imei-change:
    get:
      summary: Retrieve Devices' Last IMEI changes.
      description: >
        This endpoint provides a list of Devices' last IMEI changes within the
        time range.
      operationId: getDevicesChanges
      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'
      tags:
        - Devices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeviceImeiChanges'
        '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/devices/{deviceId}/imei-change:
    get:
      summary: Retrieve IMEI change history of a device.
      description: >
        This endpoint provides IMEI change history for a device within the time
        range.
      operationId: getDeviceChanges
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/startTime'
        - $ref: '#/components/parameters/endTime'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
      tags:
        - Devices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeviceImeiChanges'
        '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'


  ########################## [Awareness] DeviceGroups #############################

  /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'

  ########################## [Awareness] TAC Codes #################################

  /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'

  # TAC Codes Metrics — summary distribution across types, brands, models
  /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'

  # Next release: we can add support for more Query filters (e.g. SPs, APNs, ...)

  ########################## [Awareness] Security Report ##########################

  /watchtower/v1/security-report/export:
    get:
      tags:
        - Security Report
      summary: Get Monthly Security Report PDF
      description: Get Monthly Security Report PDF
      operationId: getSecurityReportPDF
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
      responses:
        '200':
          description: Successful Response
          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/security-report/summary:
    get:
      tags:
        - Security Report
      summary: Get Security Report Summary
      description: Get Summary section from Security Report
      operationId: getSecurityReportSummary
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityReportSummary'
              example:
                total_low: 19
                total_medium: 3
                total_high: 3
                overall_severity: High
                summary_text: During the month of April 2025, Aeris IoT Watchtower™ conducted a security assessment of your 105,899 provisioned devices, of which 5 were active, on the Aeris network. We encountered a total of 25 issues with 3 considered to be high risk, 3 medium risk, and 19 low risks across the categories below. In this summary, we list only the most important in each category.
                disclaimer: The results presented in this report are a point-in-time risk assessment and represent the state of security on the date it was produced. Aeris makes no representation on the completeness of the risks assessed. The risks analyzed in the section titled Security Risk Assessment Details constitute the entire analysis performed. This report is prepared for the intended recipient only and no other parties may rely on it for any purposes.
                disclaimer_no2: ICMP, DNS and NTP protocols are excluded from endpoint locations map.
                sections:
                  application_security:
                    high: 1
                    medium: 1
                    low: 0
                    highest_severity: High
                    recommended_action: Verify the legitimacy of traffic for devices communicating in non-designated / OFAC countries.
                  data_protection:
                    high: 2
                    medium: 0
                    low: 2
                    highest_severity: High
                    recommended_action: We recommend configuring your IoT devices to use encrypted protocols (HTTPS and SFTP) rather than unencrypted protocols (HTTP and FTP).
                  device_security:
                    high: 0
                    medium: 0
                    low: 15
                    highest_severity: Low
                    recommended_action: No action required at this time.
                  inventory_control_devices:
                    high: 0
                    medium: 0
                    low: 2
                    highest_severity: Low
                    recommended_action: No action required at this time.
                  net_work_security:
                    high: 0
                    medium: 2
                    low: 0
                    highest_severity: Medium
                    recommended_action: We recommend an end-to-end encrypted channel to be used for data flow between IOT devices and the customer’s application server.
                device_activated_summary:
                  - - Unknown
                    - 5
                    - 462612618
                trend_low:
                  content: +18.75%
                  direction: trend_up
                  current_value: 19
                  previous_value: 16
                trend_medium:
                  content: 0%
                  direction: trend_flat
                  current_value: 3
                  previous_value: 3
                trend_high:
                  content: '-50%'
                  direction: trend_down
                  current_value: 3
                  previous_value: 6
        '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/security-report/detail:
    get:
      tags:
        - Security Report
      summary: Get Security Report Detail
      description: Get Details section from Security Report
      operationId: getSecurityReportDetail
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityReportDetail'
              example:
                  sections:
                    inventory_control_devices:
                      - sec_no: '90'
                        tds:
                          - content: 1.1 Devices located according to expectations
                            column: security_item
                          - content: Number of devices outside their designated home location
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices outside of designated home country: Low < 5%; Medium 5% to 10%; High > 10%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '95'
                        tds:
                          - content: 1.2 Non-IoT devices in use
                            column: security_item
                          - content: Use of Non-IoT devices
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% of non-IoT devices: Low < 5%; Medium 5% to 10%; High > 10%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                    data_protection:
                      - sec_no: '100'
                        tds:
                          - content: 2.1 Encrypt Data flow to private applications
                            column: security_item
                          - content: Number of enterprise cellular connections towards applications deployed in the enterprise’s private network not using encrypted channels (ex- https or TLS)?
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% of devices using unencrypted channels: Low < 5%; Medium 5% to 10%; High > 10%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '105'
                        tds:
                          - content: 2.2 Encrypt Data flow to public applications
                            column: security_item
                          - content: Number of enterprise cellular connections towards applications deployed in the enterprise’s public network not using encrypted channels (ex- https or TLS)?
                            column: description
                          - content: '+100%'
                            direction: trend_up
                            current_value: 1
                            previous_value: 0
                            column: trend
                          - content: '1'
                            column: occurrence_count
                          - content: '1'
                            column: device_impacted
                          - content: '% of devices using unencrypted channels: Low < 5%; Medium 5% to 10%; High > 10%'
                            column: assessment_criteria
                          - content: High
                            column: assessed_severity
                          - content: We recommend configuring your IoT devices to use encrypted protocols (HTTPS and SFTP) rather than unencrypted protocols (HTTP and FTP).
                            column: recommended_action
                      - sec_no: '110'
                        tds:
                          - content: 2.3 Use of untrusted DNS servers
                            column: security_item
                          - content: Number of devices connecting to a recursive DNS that is public or untrusted
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% of devices using a public recursive DNS: Low < 5%; Medium 5% to 10%; High > 10%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '115'
                        tds:
                          - content: 2.4 Data Sovereignty
                            column: security_item
                          - content: Number of devices communicating with applications located outside the home country
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% of devices communicating with applications outside their home country: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                    net_work_security:
                      - sec_no: '120'
                        tds:
                          - content: 3.1 Devices utilizing a secure connection
                            column: security_item
                          - content: Devices utilizing VPN to connect to enterprise’s servers
                            column: description
                          - content: '+100%'
                            direction: trend_up
                            current_value: 1
                            previous_value: 0
                            column: trend
                          - content: '1'
                            column: occurrence_count
                          - content: '1'
                            column: device_impacted
                          - content: |-
                              % devices use VPN:
                              Low > 30%
                              Medium Otherwise
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '160'
                        tds:
                          - content: 3.2 Devices utilizing private APN
                            column: security_item
                          - content: The devices are using a private APN to connect to private applications, private cloud hosted applications or to internet.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices utilizing private APN: Low ≥ 0%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '165'
                        tds:
                          - content: 3.3 Devices utilizing internet APN
                            column: security_item
                          - content: The devices are using an Internet APN to connect to public cloud hosted applications or to internet.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices utilizing internet APN: Low ≥ 0%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '1200'
                        tds:
                          - content: 3.4 Manage security access controls
                            column: security_item
                          - content: Number of enforcement security policies for device traffic
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: Low if any network policy configured, Medium otherwise
                            column: assessment_criteria
                          - content: Medium
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                    application_security:
                      - sec_no: '125'
                        tds:
                          - content: '4.1 Non-compliant communications: OFAC'
                            column: security_item
                          - content: Devices communicating to endpoints in OFAC countries.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: 'Devices communicating to endpoints in OFAC countries: Low = 0; High > 0'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '130'
                        tds:
                          - content: 4.2 Public applications
                            column: security_item
                          - content: Applications reachable via the public Internet
                            column: description
                          - content: '+100%'
                            direction: trend_up
                            current_value: 54
                            previous_value: 0
                            column: trend
                          - content: '54'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: 'Number of applications reachable on the public Internet: Low = 0; Medium > 0'
                            column: assessment_criteria
                          - content: Medium
                            column: assessed_severity
                          - content: We recommend secure VPN communication instead of public internet for application communication.
                            column: recommended_action
                    device_security:
                      - sec_no: '55'
                        tds:
                          - content: 5.1 Malicious Endpoint
                            column: security_item
                          - content: Devices communicating with well-known malicious endpoints identified by their IP address
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% of devices communicating with Malicious endpoints by IP: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '60'
                        tds:
                          - content: 5.2 Botnet and C&C
                            column: security_item
                          - content: Devices communicated with an endpoint related to a malicious bot, infecting the hosts and connecting them to a central server or servers that act as a command and control (C&C) center.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing Botnet and C&C: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '65'
                        tds:
                          - content: 5.3 Cryptocurrency
                            column: security_item
                          - content: Devices communicated with an endpoint related to cryptocurrencies.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing Cryptocurrency: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '70'
                        tds:
                          - content: 5.4 Data Exfiltration
                            column: security_item
                          - content: Devices communicated with an endpoint participating in data exfiltration.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing Data Exfiltration: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '80'
                        tds:
                          - content: 5.5 Phishing
                            column: security_item
                          - content: Devices communicated with email messages that look like they are from a trusted business but are actually connected to phishing websites.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing Phishing: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '85'
                        tds:
                          - content: 5.6 Ransomware
                            column: security_item
                          - content: Devices communicated with an endpoint known to have ransomware.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing Ransomware: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '10'
                        tds:
                          - content: 5.7 Suspicious device behavior - Address Scan
                            column: security_item
                          - content: Devices scanning the addresses of other devices in their subnet
                            column: description
                          - content: '+100%'
                            direction: trend_up
                            current_value: 1
                            previous_value: 0
                            column: trend
                          - content: '1'
                            column: occurrence_count
                          - content: '1'
                            column: device_impacted
                          - content: '% devices showing address scan events: Low = 0%; Medium 0% to 0.1%; High > 0.1%'
                            column: assessment_criteria
                          - content: High
                            column: assessed_severity
                          - content: Verify the integrity of these devices that have been performing unusual address scans.
                            column: recommended_action
                      - sec_no: '30'
                        tds:
                          - content: 5.8 Suspicious device behavior - Port Scan
                            column: security_item
                          - content: Devices scanning ports beyond their normal connection to the endpoint
                            column: description
                          - content: '+100%'
                            direction: trend_up
                            current_value: 1
                            previous_value: 0
                            column: trend
                          - content: '1'
                            column: occurrence_count
                          - content: '1'
                            column: device_impacted
                          - content: '% devices showing port scan events: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: High
                            column: assessed_severity
                          - content: Verify the integrity of these devices that have been performing unusual port scans.
                            column: recommended_action
                      - sec_no: '35'
                        tds:
                          - content: 5.9 Suspicious Behavior - SIM misuse
                            column: security_item
                          - content: Devices having their SIM swapped
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing SIM misuse alarm: Low = 0%; Medium 0% to 0.1%; High > 0.1%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '75'
                        tds:
                          - content: 5.10 Suspicious Endpoint
                            column: security_item
                          - content: Devices communicated with a domain that has not been established and is serving temporary content on its base page (a parked domain).
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing Suspicious Endpoint: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '20'
                        tds:
                          - content: 5.11 Anomalous Behavior - New destination IPs
                            column: security_item
                          - content: Devices attached to unexpected new destination IP addresses on the network
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing new IP addresses: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '40'
                        tds:
                          - content: 5.12 Anomalous Behavior - TCP Bad Flags
                            column: security_item
                          - content: Devices having unexpected use of TCP flags.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: 'Frequency of TCP bad flag events per week: Low < 10; Medium 10 to 100; High > 100'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '45'
                        tds:
                          - content: 5.13 Anomalous Behavior - TCP large flow count
                            column: security_item
                          - content: Devices having unexpected large count of TCP flows.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing large TCP flow count: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '50'
                        tds:
                          - content: 5.14 Anomalous Behavior - Traffic Spike
                            column: security_item
                          - content: Devices having unexpected large occurrence of traffic spike.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% devices showing traffic spike: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '175'
                        tds:
                          - content: 5.15 Anomalous Mobility Event - Moving Outside a Location List
                            column: security_item
                          - content: The device has been identified outside the location list associated with one of the device groups this device belongs to.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% anomalous mobility events - moving outside location list: Low < 0.1%; Medium 0.1% to 0.5%; Critical > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '180'
                        tds:
                          - content: 5.16 Anomalous Mobility Event - Impossible Mobility
                            column: security_item
                          - content: The device has been moving across different locations at a speed that is beyond reasonable (900 km/h).
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% anomalous mobility events - impossible mobility: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                      - sec_no: '140'
                        tds:
                          - content: 5.17 Blocked Flows
                            column: security_item
                          - content: Blocked Flows by a security policy.
                            column: description
                          - content: '0%'
                            direction: trend_flat
                            current_value: 0
                            previous_value: 0
                            column: trend
                          - content: '0'
                            column: occurrence_count
                          - content: '0'
                            column: device_impacted
                          - content: '% showing Blocked Flows: Low < 0.1%; Medium 0.1% to 0.5%; High > 0.5%'
                            column: assessment_criteria
                          - content: Low
                            column: assessed_severity
                          - content: No action required at this time.
                            column: recommended_action
                  category:
                    inventory_control_devices: 1. Inventory and Control of Devices
                    data_protection: 2. Data Protection
                    net_work_security: 3. Network Security
                    application_security: 4. Application Security
                    device_security: 5. Device Security
        '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/security-report/device-location:
    get:
      tags:
        - Security Report
      summary: Get Security Report Device Location Tables
      description: Get Device Location section from Security Report
      operationId: getSecurityReportDevice
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityReportDeviceUsage'
              example:
                total: 1
                data:
                  - - active_devices: 0
                      device_country: string
                      data_usage_bytes: 0
        '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/security-report/endpoint-location:
    get:
      tags:
        - Security Report
      summary: Get Security Report Endpoint Location Tables
      description: Get Endpoint Location section from Security Report
      operationId: getSecurityReportEndpoint
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityReportEndpoint'
              example:
                total: 1
                data:
                  - - endpoint_country: United States
                      device_count: 5
                      endpoint_count: 385
                      data_usage_bytes: 12131923
                      ip_flows: 8320
        '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/security-report/appendix/search:
    post:
      tags:
        - Security Report
      summary: Get Security Report Appendix
      description: Get Appendix report of an account for a specific month
      operationId: getSecurityReportAppendix
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityReportAppendixRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSecurityReportAppendix'
        '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/security-report/appendix/export:
    post:
      summary: Export Security Report Appendix
      description: Export Security Report Appendix
      tags:
        - Security Report
      operationId: exportSecurityReportAppendix
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/year'
        - $ref: '#/components/parameters/month'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityReportAppendixTrigger'
      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'


  ########################## Activity Logs ########################################
  /watchtower/v1/activity-logs/device-groups/search:
    post:
      summary: Get device group activity logs
      description: Get activity logs of a device group
      operationId: getActivityLogsDeviceGroups
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceGroupActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeviceGroupActivityLog'
        '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/activity-logs/events/search:
    post:
      summary: Get events activity logs
      description: Get events life cycle activity logs
      operationId: getActivityLogsEvents
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEventActivityLog'
        '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/activity-logs/events/configs/search:
    post:
      summary: Get event configs activity logs
      description: Get event configs activity logs
      operationId: getActivityLogsEventConfigs
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventConfigActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEventConfigActivityLog'
        '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/activity-logs/event-policies/search:
    post:
      summary: Get event policy activity logs
      description: Search activity logs for event policies
      operationId: getActivityLogsEventPolicies
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPolicyActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEventPolicyActivityLog'
        '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/activity-logs/event-policies/export:
    post:
      summary: Export Event Policy Activity Logs
      description: Use this endpoint to export Event Policy Activity Logs as CSV.
      operationId: exportActivityLogsEventPolicies
      tags:
        - Activity Logs
      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/EventPolicyActivityLogQuery'
      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/activity-logs/applications/search:
    post:
      summary: Get applications activity logs
      description: Get applications activity logs
      operationId: getActivityLogsApplications
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedApplicationActivityLog'
        '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/activity-logs/protection-policies/search:
    post:
      summary: Get protection policies activity logs
      description: Get protection policies activity logs
      operationId: getActivityLogsProtectionPolicies
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtectionPolicyActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedProtectionPolicyActivityLog'
        '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/activity-logs/enforcement-rules/search:
    post:
      summary: Get enforcement rules activity logs
      description: Get enforcement rules activity logs
      operationId: getActivityLogsEnforcementRules
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRuleActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnforcementRuleActivityLog'
        '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/activity-logs/location-lists/search:
    post:
      description: Get location lists activity logs
      operationId: getActivityLogsLocationLists
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationListActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedLocationListActivityLog'
        '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'

  ########################## [Enforcement] Applications ###################################
  /watchtower/v1/activity-logs/service-configurations/search:
    post:
      summary: Get service configuration activity logs
      description: Get service configuration activity logs
      operationId: getActivityLogsServiceConfigurations
      tags:
        - Activity Logs
      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'
        - $ref: '#/components/parameters/sort'
        - name: serviceConfigurationType
          in: query
          required: false
          schema:
            type: string
          description: Filter by service configuration type (e.g. SPLIT_BILLING, RATE_LIMIT).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceConfigurationActivityLogQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedServiceConfigurationActivityLog'
        '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/applications:
    post:
      summary: Create an application
      operationId: createApplication
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCreateRequest'
      responses:
        '201':
          description: Application created successfully
          content:
            application/json:
              schema:
                type: integer
                format: int64
        '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/applications/search:
    post:
      summary: Search applications
      operationId: searchApplications
      tags:
        - Applications
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationsQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedApplications'
        '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/applications/{applicationId}:
    get:
      summary: Get an application
      operationId: getApplication
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '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'
    put:
      summary: Update an existing application
      operationId: updateApplication
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/applicationId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdateRequest'
      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 an application
      operationId: deleteApplication
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/applicationId"
      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'

  ########################## [Enforcement] Protection Policies ###################################
  /watchtower/v1/protection-policies:
    post:
      summary: Create a protection policy
      operationId: createProtectionPolicy
      tags:
        - Protection Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtectionPolicyCreateRequest'
      responses:
        '201':
          description: Protection policy created successfully
          content:
            application/json:
              schema:
                type: integer
                format: int64
        '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/protection-policies/search:
    post:
      summary: Search protection policies
      operationId: searchProtectionPolicies
      tags:
        - Protection Policies
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtectionPoliciesQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedProtectionPolicies'
        '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/protection-policies/{protectionPolicyId}:
    get:
      summary: Get a protection policy
      operationId: getProtectionPolicy
      tags:
        - Protection Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: '#/components/parameters/protectionPolicyId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectionPolicy'
        '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'
    put:
      summary: Update an existing protection policy
      operationId: updateProtectionPolicy
      tags:
        - Protection Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/protectionPolicyId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtectionPolicyUpdateRequest'
      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 protection policy
      operationId: deleteProtectionPolicy
      tags:
        - Protection Policies
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/protectionPolicyId"
      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'

  ########################## [Enforcement] Enforcement Rules ###################################
  /watchtower/v1/enforcement-rules:
    post:
      summary: Create an enforcement rule
      operationId: createEnforcementRule
      tags:
        - Enforcement Rules
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRuleCreateRequest'
      responses:
        '201':
          description: Enforcement rule created successfully
          content:
            application/json:
              schema:
                type: integer
                format: int64
        '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/enforcement-rules/search:
    post:
      summary: Search enforcement rules
      operationId: searchEnforcementRules
      tags:
        - Enforcement Rules
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRulesQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnforcementRules'
        '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/enforcement-rules/{enforcementRuleId}:
    get:
      summary: Get an enforcement rule
      operationId: getEnforcementRule
      tags:
        - Enforcement Rules
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: '#/components/parameters/enforcementRuleId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnforcementRule'
        '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'
    put:
      summary: Update an existing enforcement rule
      operationId: updateEnforcementRule
      tags:
        - Enforcement Rules
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/enforcementRuleId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRuleUpdateRequest'
      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 an enforcement rule
      operationId: deleteEnforcementRule
      tags:
        - Enforcement Rules
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/enforcementRuleId"
      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/enforcement-rules/{enforcementRuleId}/activate:
    post:
      summary: Activate an enforcement rule
      operationId: activateEnforcementRule
      tags:
        - Enforcement Rules
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/enforcementRuleId'
      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'

  /watchtower/v1/enforcement-rules/{enforcementRuleId}/deactivate:
    post:
      summary: Deactivate an enforcement rule
      operationId: deactivateEnforcementRule
      tags:
        - Enforcement Rules
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/enforcementRuleId'
      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'

  ########################## [Enforcement] Rate Limiters ###################################
  /watchtower/v1/rate-limiters:
    post:
      summary: Create rate limiter definitions
      description: Creates rate limiters (one per config entry) for the given account under a shared name.
      operationId: createRateLimiter
      tags:
        - Rate Limiters
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalRateLimiterCreateRequest'
      responses:
        '201':
          description: Rate limiters created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalRateLimiterListResponse'
        '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/rate-limiters/search:
    post:
      summary: Search rate limiters
      description: Retrieves rate limiters for the given account, with optional filtering.
      operationId: searchRateLimiters
      tags:
        - Rate Limiters
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalRateLimitersQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedRateLimiters'
        '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/rate-limiters/{rateLimiterId}:
    get:
      summary: Get a rate limiter by ID
      operationId: getRateLimiter
      tags:
        - Rate Limiters
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: '#/components/parameters/rateLimiterId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimiter'
        '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'
    put:
      summary: Update a rate limiter definition
      operationId: updateRateLimiter
      tags:
        - Rate Limiters
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/rateLimiterId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalRateLimiterUpdateRequest'
      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 rate limiter definition
      operationId: deleteRateLimiter
      tags:
        - Rate Limiters
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/rateLimiterId"
      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'

  ########################## Location Lists ###################################
  /watchtower/v1/location-lists:
    post:
      summary: Create a location list
      operationId: createLocationList
      tags:
        - Location Lists
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationListCreateRequest'
      responses:
        '201':
          description: Location list created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationList'
        '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/location-lists/search:
    post:
      summary: Search location lists
      operationId: searchLocationLists
      tags:
        - Location Lists
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationListQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedLocationLists'
        '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/location-lists/suggest-entries:
    post:
      summary: Suggest entries for a location list
      operationId: suggestLocationListEntries
      tags:
        - Location Lists
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationListSuggestionRequest'
      responses:
        '200':
          description: Suggested entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LocationListEntry'
        '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/location-lists/{locationListId}:
    get:
      summary: Get location list details
      operationId: getLocationList
      tags:
        - Location Lists
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/locationListId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationList'
        '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 location list
      operationId: updateLocationList
      tags:
        - Location Lists
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/locationListId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationListUpdateRequest'
      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 location list
      operationId: deleteLocationList
      tags:
        - Location Lists
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: "#/components/parameters/accountId"
        - $ref: "#/components/parameters/locationListId"
      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'

  ########################## [Awareness] Flow Aggregates Metrics #################
  /watchtower/v1/flow-aggregates/metrics/search:
    post:
      summary: Get Account Flow Aggregates Metrics
      description: |
        Returns daily aggregated security metrics for an account across a date range.
        Supported metrics: unique_endpoint_ip_count, unique_endpoint_fqdn_count,
        avg_mo_data_bytes_per_transaction, avg_mt_data_bytes_per_transaction,
        imei_change_event_count, public_dns_query_count, private_dns_query_count,
        total_mo_data_bytes, total_mt_data_bytes.

        The maximum allowed period between `startDate` and `endDate` is 90 days. Requests exceeding this limit return `400 Bad Request`.
      operationId: getFlowAggregatesMetrics
      tags:
        - Flows
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDailyMetricsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedSummaryTableData'
        '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'

  ########################## [Awareness] Device Deep Forensics ####################

  # Device Flow Aggregates Metrics Chart (merged: data-transactions, destination-endpoints, dns-queries)
  /watchtower/v1/devices/flow-aggregates/metrics/search:
    post:
      summary: Get Device Metrics Chart
      description: >
        Returns hourly time-series of device network metrics for a single device.
        Use `metricGroup` to select which group of metrics to retrieve:

        - `DATA_TRANSACTIONS` — average data per transaction
          (`avgMoDataBytes`, `avgMtDataBytes`).

        - `DATA_VOLUME` — total data volume
          (`sumMoDataBytes`, `sumMtDataBytes`).

        - `DNS_QUERIES` — DNS activity metrics
          (`privateOccurrences`, `publicOccurrences`).
          Optional DNS filter fields: `isPublicDns`, `domainHosts`, `domainHostsOperation`.

        - `DESTINATION_ENDPOINTS` — unique destination count
          (`uniqueServerIpCount`).

        - `IP_FLOWS` — IP flow event count (`occurrences`).
          Optional IP-flow filter fields: `sourceIp`, `sourcePort`, `destinationPort`.

        Only metric fields belonging to the requested group are populated in the response;
        all other metric fields are `null`. A `400` is returned if group-specific filter
        fields are used with the wrong group.
      operationId: getDeviceFlowAggregatesMetrics
      tags:
        - Devices
      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/DeviceMetricsChartRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceMetricsChartResponse'
        '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'

  # Flow Aggregates Table (merged: data-transactions + destination-endpoints)
  /watchtower/v1/devices/flow-aggregates/search:
    post:
      summary: Get Flow Aggregates Table
      description: >
        Returns a paginated breakdown of network flow aggregates for a specific device,
        grouped by destination endpoint (server FQDN, IP, protocol, port), including
        occurrence counts and total MO/MT/combined byte volumes per group. Scope the
        query to a device via `iccid` in the request body and apply optional filters
        by destination FQDN, IP, application protocol, or port.
      operationId: getDeviceFlowAggregatesTable
      tags:
        - Devices
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceFlowTableRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedFlowAggregatesTable'
        '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'

  # DNS Queries Table
  /watchtower/v1/devices/dns-queries/search:
    post:
      summary: Get DNS Queries Table
      description: >
        Returns a paginated breakdown of DNS Queries for a specific device,
        grouped by DNS server (FQDN, IP, protocol, port, public/private type).
        Scope to a device via `iccid`, optionally filter by DNS FQDN/IP, protocol,
        port, or public/private type. Use `domainHosts` with `domainHostsOperation`
        to include or exclude specific DNS servers (max 1000 entries);
        `domainHostsOperation` defaults to `in` when omitted.
      operationId: getDeviceDnsQueriesTable
      tags:
        - Devices
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DnsQueriesTableRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDnsQueriesTable'
        '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'

  # Device IP Flows Table
  /watchtower/v1/devices/ip-flows/search:
    post:
      summary: Search Device IP Flows
      description: >
        Returns a paginated list of raw IP flow records for a specific device, with
        per-flow timing, source/destination endpoint, and data volume detail. Scope
        to a device via `iccid` and filter optionally by destination/source FQDN,
        IP, protocol, or port. Default sort: `startTime:asc`.

        **Distinct from `POST /watchtower/v1/ip-flows/search`:**
        - This endpoint is **device-scoped** via `iccid` and returns raw per-flow
          metric records (timing, bytes, source/destination) without enforcement context.
        - The account-level `/ip-flows/search` searches across all devices and returns
          structured `BLOCKED`/`ALLOWED` flow DTOs with policy enforcement detail.
      operationId: getDeviceIpFlows
      tags:
        - Devices
      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'
        - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceIpFlowFilter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedIpFlowMetricsTable'
        '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'


  ########################## Gateway ###########################################

  /watchtower/v1/gateways:

    get:
      tags:
        - Gateway
      summary: List gateways by company
      operationId: listGateways
      parameters:
        - name: companyId
          in: query
          required: true
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
            description: Filter by device status (Active, Suspended, Terminated)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GatewayResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '400':
          $ref: '#/components/responses/400Configuration'
        '500':
          $ref: '#/components/responses/500'

    post:
      tags:
        - Gateway
      summary: Provision a gateway
      operationId: provisionGateway
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            description: Client-supplied idempotency key (UUID). Same key replays the cached response.
        - name: X-Watchtower-Trace-Id
          in: header
          required: false
          schema:
            type: string
            description: Correlation ID propagated through all downstream calls and stored in BigQuery.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayProvisionRequest'
      responses:
        '201':
          description: Gateway provisioned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409Configuration'
        '400':
          $ref: '#/components/responses/400Configuration'
        '503':
          $ref: '#/components/responses/503Configuration'
        '500':
          $ref: '#/components/responses/500'

  /watchtower/v1/gateways/{gatewayId}:

    get:
      tags:
        - Gateway
      summary: Get gateway by ID
      operationId: getGateway
      parameters:
        - name: gatewayId
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '400':
          $ref: '#/components/responses/400Configuration'
        '500':
          $ref: '#/components/responses/500'

    put:
      tags:
        - Gateway
      summary: Update gateway fields
      operationId: updateGateway
      parameters:
        - name: gatewayId
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            description: Client-supplied idempotency key (UUID). Same key replays the cached response.
        - name: X-Watchtower-Trace-Id
          in: header
          required: false
          schema:
            type: string
            description: Correlation ID propagated through all downstream calls.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayUpdateRequest'
      responses:
        '204':
          description: Gateway updated successfully
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '400':
          $ref: '#/components/responses/400Configuration'
        '500':
          $ref: '#/components/responses/500'

    delete:
      tags:
        - Gateway
      summary: Deprovision a gateway
      operationId: deprovisionGateway
      parameters:
        - name: gatewayId
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            description: Client-supplied idempotency key (UUID). Same key replays the cached response.
        - name: X-Watchtower-Trace-Id
          in: header
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Gateway deprovisioned successfully
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409Configuration'
        '400':
          $ref: '#/components/responses/400Configuration'
        '503':
          $ref: '#/components/responses/503Configuration'
        '500':
          $ref: '#/components/responses/500'

  /watchtower/v1/gateways/{gatewayId}/history:

    get:
      tags:
        - Gateway
      summary: Get gateway state-change history
      operationId: getGatewayHistory
      parameters:
        - name: gatewayId
          in: path
          required: true
          schema:
            type: string
        - name: companyId
          in: query
          required: true
          schema:
            type: string
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Start of time window (ISO 8601). Defaults to 31 days ago.
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: End of time window (ISO 8601). Defaults to now.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GatewayHistoryResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /watchtower/v1/batch/gateways:

    post:
      tags:
        - Gateway
      summary: Batch provision gateways
      operationId: batchProvisionGateways
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            description: Client-supplied idempotency key (UUID). Same key replays the cached response.
        - name: X-Watchtower-Trace-Id
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGatewayProvisionRequest'
      responses:
        '202':
          description: Batch accepted — partial failures listed in the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGatewayProvisionResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '400':
          $ref: '#/components/responses/400Configuration'
        '500':
          $ref: '#/components/responses/500'

    delete:
      tags:
        - Gateway
      summary: Batch deprovision gateways
      operationId: batchDeprovisionGateways
      parameters:
        - name: X-Watchtower-Trace-Id
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGatewayDeprovisionRequest'
      responses:
        '202':
          description: Batch accepted — partial failures listed in the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGatewayDeprovisionResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '400':
          $ref: '#/components/responses/400Configuration'
        '500':
          $ref: '#/components/responses/500'


########################## components ###########################################
components:

  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: This API uses OAuth 2 with the Client Credentials flow.
      flows:
        clientCredentials:
          tokenUrl: /watchtower/v1/auth/token
          scopes: { }

  parameters:
    authorization:
      name: Authorization
      in: header
      description: Bearer Token for authentication
      required: true
      schema:
        type: string
        pattern: '^Bearer [A-Za-z0-9-._~+/]+=*$'
      example: 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
    accountId:
      name: X-Watchtower-Account-Id
      in: header
      description: Account Id
      required: true
      schema:
        $ref: '#/components/schemas/accountId'
      example: 1002000010
    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'
    startDate:
      name: startDate
      in: query
      required: true
      description: The inclusive start date (UTC), format YYYY-MM-DD. Maximum period between startDate and endDate is 90 days.
      example: '2026-05-29'
      schema:
        type: string
        format: date
    endDate:
      name: endDate
      in: query
      required: true
      description: The inclusive end date (UTC), format YYYY-MM-DD. Maximum period between startDate and endDate is 90 days.
      example: '2026-06-05'
      schema:
        type: string
        format: date
    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'
    limit:
      name: limit
      in: query
      description: The number of items to retrieve per page (10000 max).
      schema:
        $ref: '#/components/schemas/limit'
    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
    reportId:
      name: reportId
      in: path
      description: Report Id
      required: true
      schema:
        type: string
      example: b7e72bb3-b2fd-4265-a28b-9a279418fdb9
    deviceId:
      name: deviceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/deviceId'
    year:
      name: year
      description: Year
      in: query
      required: true
      schema:
        type: integer
        maximum: 2099
        minimum: 2000
    month:
      name: month
      description: Month
      in: query
      required: true
      schema:
        type: integer
        maximum: 12
        minimum: 1

    # Events
    eventId:
      name: eventId
      in: path
      description: Event Id
      required: true
      schema:
        $ref: '#/components/schemas/EventId'
    eventConfigId:
      name: eventConfigId
      in: path
      description: Event Configuration Id
      required: true
      schema:
        type: integer
    suppressionConfigId:
      name: suppressionConfigId
      in: path
      description: Event Suppression Configuration Id
      required: true
      schema:
        type: integer
        format: int64
    undoDismissedEvents:
      name: undoDismissedEvents
      in: query
      description: Whether to undo past events dismissed by this suppression config or not
      required: true
      schema:
        type: boolean
        default: false

    # DeviceGroups
    deviceGroupId:
      name: deviceGroupId
      in: path
      required: true
      description: The ID of the device group
      schema:
        type: integer

    # Applications
    applicationId:
      name: applicationId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/applicationId'

    # ProtectionPolicies
    protectionPolicyId:
      name: protectionPolicyId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/protectionPolicyId'

    # EnforcementRules
    enforcementRuleId:
      name: enforcementRuleId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/enforcementRuleId'

    # RateLimiters
    rateLimiterId:
      name: rateLimiterId
      in: path
      required: true
      description: The ID of the rate limiter
      schema:
        type: integer
        format: int64

    # EventPolicies
    policyId:
      name: policyId
      in: path
      required: true
      description: The ID of the event policy
      schema:
        type: integer
        format: int64

    # LocationLists
    locationListId:
      name: locationListId
      in: path
      required: true
      description: The ID of the location list
      schema:
        type: integer
        format: int64

  schemas:
    GatewayUpdateRequest:
      type: object
      description: Partial update for a gateway. Only provided fields are updated.
      properties:
        serialNumber:
          type: string
          nullable: true
        deviceType:
          type: string
          nullable: true
        firmwareVersion:
          type: string
          nullable: true
        imei:
          type: string
          nullable: true
          pattern: '^\d{15}$'
        mcc:
          type: string
          nullable: true
          pattern: '^\d{3}$'
        mnc:
          type: string
          nullable: true
          pattern: '^\d{2,3}$'
        attributes:
          type: object
          additionalProperties:
            type: string
          nullable: true
        billing:
          type: object
          nullable: true
          properties:
            billingStatus:
              type: string

    GatewayProvisionRequest:
      type: object
      required:
        - gatewayId
        - companyId
      properties:
        gatewayId:
          type: string
          description: Gateway device identifier — 15-digit IMSI
          pattern: '^\d{15}$'
        companyId:
          type: string
          description: FK → Company; must already exist in the company registry
        mcc:
          type: string
          description: Mobile Country Code — 3-digit numeric string
          pattern: '^\d{3}$'
          nullable: true
        mnc:
          type: string
          description: Mobile Network Code — 2–3 digit numeric string
          pattern: '^\d{2,3}$'
          nullable: true
        iccid:
          type: string
          description: Integrated Circuit Card Identifier — 18–22 digit numeric string
          pattern: '^\d{18,22}$'
          nullable: true
        imei:
          type: string
          description: International Mobile Equipment Identity — exactly 15 digits
          pattern: '^\d{15}$'
          nullable: true
        serialNumber:
          type: string
          description: Device serial number (e.g. MR40-QA-00050001)
          nullable: true
        deviceType:
          type: string
          description: Device type classification (e.g. CAT20)
          nullable: true
        firmwareVersion:
          type: string
          description: Firmware version string
          nullable: true
        billing:
          type: object
          nullable: true
          description: Billing information
          properties:
            plan:
              type: string
              nullable: true
            usedDataMb:
              type: number
              format: double
              nullable: true
            usedDataGb:
              type: number
              format: double
              nullable: true
            billingStatus:
              type: string
              nullable: true
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Optional custom key-value attributes stored as device custom_field entries
          nullable: true
        apn:
          type: string
          description: APN hint from caller — always overridden by server-side configuration
          nullable: true

    GatewayHistoryResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique event ID (UUID)
        gatewayId:
          type: string
          description: Gateway device identifier (IMSI)
        fromStatus:
          type: string
          nullable: true
          description: Previous status — null for initial PROVISION event
        toStatus:
          type: string
          description: Status after transition
        reason:
          type: string
          description: "Transition reason: PROVISION / TERMINATION"
        traceId:
          type: string
          nullable: true
          description: X-Watchtower-Trace-Id from the originating request
        occurredAt:
          type: string
          format: date-time
          description: Wall-clock time of the transition

    BatchGatewayProvisionRequest:
      type: object
      required:
        - gateways
      properties:
        gateways:
          type: array
          maxItems: 5000
          items:
            $ref: '#/components/schemas/GatewayProvisionRequest'

    BatchGatewayProvisionResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total records received
        provisioned:
          type: integer
          description: Successfully provisioned
        updated:
          type: integer
          description: Already existed and were idempotently returned
        rejected:
          type: integer
          description: Failed validation or enrichment
        failures:
          type: array
          items:
            $ref: '#/components/schemas/BatchFailureRecord'

    BatchFailureRecord:
      type: object
      properties:
        gatewayId:
          type: string
          description: Gateway ID from the original request (may be invalid)
        failureCategory:
          type: string
          description: "High-level category: validation / company_not_found / ip_enrichment"
        failureReason:
          type: string
          description: Specific reason code (e.g. MISSING_GATEWAY_ID, IPAM_NON_2XX)

    BatchGatewayDeprovisionRequest:
      type: object
      required:
        - gateways
      properties:
        gateways:
          type: array
          maxItems: 5000
          items:
            $ref: '#/components/schemas/GatewayDeprovisionItem'

    GatewayDeprovisionItem:
      type: object
      required:
        - gatewayId
        - companyId
      properties:
        gatewayId:
          type: string
          description: IMSI of the gateway to deprovision
        companyId:
          type: string
          description: Company owning the gateway

    BatchGatewayDeprovisionResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total records received
        terminated:
          type: integer
          description: Successfully terminated
        skipped:
          type: integer
          description: Skipped (already terminated or not found)
        rejected:
          type: integer
          description: Failed validation or IPAM release
        failures:
          type: array
          items:
            $ref: '#/components/schemas/BatchDeprovisionFailureRecord'

    BatchDeprovisionFailureRecord:
      type: object
      properties:
        gatewayId:
          type: string
          description: Gateway ID from the original request
        failureCategory:
          type: string
          description: "High-level category: validation / ipam_failed / not_found / already_terminated"
        failureReason:
          type: string
          description: Specific reason code

    ConfigurationErrorResponse:
      type: object
      description: RFC 7807 error envelope (FS section 4.7)
      properties:
        title:
          type: string
          description: Human-readable error summary
          example: "Payload validation failed"
        status:
          type: integer
          description: HTTP status code
          example: 422
        correlationId:
          type: string
          description: Trace / correlation ID (X-Watchtower-Trace-Id or auto-generated UUID)
          example: "c7f5a8b2-1234-5678-abcd-ef0123456789"
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationErrorDetail'

    ConfigurationErrorDetail:
      type: object
      properties:
        field:
          type: string
          nullable: true
          description: Field name that caused the error (null for non-field errors)
          example: "gatewayId"
        code:
          type: string
          description: Machine-readable error code
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Human-readable error message
          example: "must be exactly 15 digits"

    CompanyResponse:
      type: object
      properties:
        companyId:
          type: string
          description: Primary key — unique company identifier
        name:
          type: string
          description: Human-readable display name
        parentCompanyId:
          type: string
          nullable: true
          description: Parent company in the hierarchy; null = root account
        companyType:
          type: string
          description: Company type classification
        carrierId:
          type: string
          nullable: true
          description: FK → Carrier (operator id)

    CompanyUpsertRequest:
      type: object
      required:
        - companyId
        - name
      properties:
        companyId:
          type: string
          description: Primary key — must match an entry in the company hierarchy
        name:
          type: string
          description: Human-readable display name
        parentCompanyId:
          type: string
          nullable: true
          description: Parent company in the hierarchy; null = root account

    GatewayResponse:
      type: object
      properties:
        deviceId:
          type: string
          description: Internal BigQuery entity_id for the device
        gatewayId:
          type: string
          description: Gateway device identifier (IMSI)
        companyId:
          type: string
          description: FK → Company
        status:
          type: string
          description: Device lifecycle status (Active, Suspended, Terminated)
        carrierId:
          type: string
          description: FK → Carrier (operator id)
        imei:
          type: string
          nullable: true
          description: International Mobile Equipment Identity — exactly 15 digits
        iccid:
          type: string
          nullable: true
          description: Integrated Circuit Card Identifier
        mcc:
          type: string
          nullable: true
          description: Mobile Country Code — 3-digit numeric string
        mnc:
          type: string
          nullable: true
          description: Mobile Network Code — 2–3 digit numeric string
        serialNumber:
          type: string
          nullable: true
          description: Device serial number
        deviceType:
          type: string
          nullable: true
          description: Device type classification
        firmwareVersion:
          type: string
          nullable: true
          description: Firmware version string
        billingStatus:
          type: string
          nullable: true
          description: Billing / SIM subscription state
        assignedIp:
          type: string
          nullable: true
          description: IP address assigned by IPAM
        apn:
          type: string
          nullable: true
          description: APN (Access Point Name) assigned to this gateway
        correlationId:
          type: string
          nullable: true
          description: Correlation / trace ID
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: Creation timestamp
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Custom attributes
          nullable: true

    AuthorizedAccountsResponse:
      type: object
      description: Paginated list of managed enterprise accounts
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ManagedAccount'
          description: List of managed enterprise accounts
        offset:
          type: integer
          description: Current offset
          example: 0
        limit:
          type: integer
          description: Page size
          example: 20
        total:
          type: integer
          format: int64
          description: Total number of managed accounts
          example: 1847
    ManagedAccount:
      type: object
      description: A managed enterprise account
      properties:
        accountId:
          type: integer
          format: int64
          description: Enterprise account ID
          example: 10200001
        accountName:
          type: string
          description: Account display name
          example: "Swisscom Enterprise AG"
    accountId:
      description: Account Id.
      type: integer
      format: int32
      example: 10407
      minimum: 0
    dateTime:
      description: ISO 8601 date time
      type: string
      format: date-time
      example: '2021-07-04T17:36:47Z'
    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
    total:
      type: integer
      format: int64
      description: Total number of items available.
      example: 1
      minimum: 0
    iccid:
      description: Integrated Circuit Card Identifier.
      type: string
      minLength: 18
      maxLength: 22
      example: '891004234814455936'
    imei:
      description: IMEI (International Mobile Equipment Identity) of the device.
      type: string
      minLength: 14
      maxLength: 15
      example: '86715704097269'
    imsi:
      description: International Mobile Subscriber Identifier of the device.
      type: string
      maxLength: 15
      example: '310009133100012'
    msisdn:
      description: Mobile Station International Subscriber Directory Number.
      type: string
      maxLength: 15
      example: '8801500121121'
    deviceProfileId:
      description: Device Profile ID assigned to the device.
      type: string
      maxLength: 30
      example: AER0000007087071
    ip:
      type: string
      description: IP Address
      example: 172.16.1.3
    port:
      type: integer
      description: Port number
      minimum: 0
      maximum: 65536
      example: 8080
    domain:
      description: FQDN
      type: string
      example: abc.xyz.com
    endpointFQDN:
      description: Fully qualified domain name of the endpoint
      type: string
      maxLength: 253
      minLength: 1

    ##### Generic
    ReportStatus:
      description: Report status
      type: string
      example: Processing
      enum:
        - Success
        - Processing
        - Error
        - NotStarted
    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
    ScheduledReportStatus:
      type: object
      properties:
        message:
          type: string
          example: Report processed successfully.
        error:
          type: boolean
          example: false
        status:
          $ref: '#/components/schemas/ReportStatus'
        signedUrl:
          description: Report URL
          type: string
          example: https://storage.googleapis.com/watchtower-reports/7ae9e22d-8ad4-4a69-950a-6b13d75f0c74?X-Goog-Algorithm=GOOG4-RSA-SHA
        createdAt:
          description: Creation date
          type: string
          example: 2025-06-11T14:04:59Z
    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
    Pagination:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/total'
        offset:
          $ref: '#/components/schemas/offset'
        limit:
          $ref: '#/components/schemas/limit'

    ##### Events
    EventId:
      type: string
      description: Event Id
      example: v1_1652823856823_6b71e284b63a527caa6296a66e9fdd0c
      maxLength: 128
      minLength: 1
    EventSeverity:
      description: Severity of the Event
      type: string
      example: Critical
      enum:
        - Critical
        - High
        - Medium
        - Low
      x-enum-varnames:
        - Critical
        - High
        - Medium
        - Low
    EventStatus:
      description: Status of the Event
      type: string
      example: Saved For Review
      enum:
        - New
        - Saved For Review
        - In Process
        - Resolved
        - Dismissed
      x-enum-varnames:
        - New
        - SavedForReview
        - InProcess
        - Resolved
        - Dismissed
    EventType:
      type: string
      description: Type of the Event
      example: Malicious Endpoint
      enum:
        - Address Scan
        - Botnet and C&C
        - Cryptocurrency
        - Data Exfiltration
        - Malicious Endpoint
        - New IP
        - New Port
        - Phishing
        - Port Scan
        - Ransomware
        - SIM Misuse
        - Suspicious Endpoint
        - TCP Bad Flags
        - TCP Max Flows
        - Traffic Spike
        - Unclassified
        - "Anomalous Mobility: Moving Outside Location List"
        - "Anomalous Mobility: Impossible Mobility"
        - High Frequency Reconnect
        - High Cell Disconnect Rate
      x-enum-varnames:
        - AddressScan
        - BotnetAndCnC
        - Cryptocurrency
        - DataExfiltration
        - MaliciousEndpoint
        - NewIP
        - NewPort
        - Phishing
        - PortScan
        - Ransomware
        - SIMMisuse
        - SuspiciousEndpoint
        - TCPBadFlags
        - TCPMaxFlows
        - TrafficSpike
        - Unclassified
        - AnomalousMobilityMovingOutsideLocationList
        - AnomalousMobilityImpossibleMobility
        - HighFrequencyReconnect
        - HighCellDisconnectRate
    EventCategory:
      type: string
      description: Category of the Event
      example: Malicious
      enum:
        - Malicious
        - Suspicious
        - Anomalous
    EventConfigSuppressionPeriodType:
      type: string
      enum:
        - ALWAYS
        - DURING_TIME_PERIOD
    EventDeviceGroup:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
          example: Group1
        colorCode:
          type: string
          example: '#123aaff'
    Event:
      type: object
      properties:
        eventId:
          $ref: '#/components/schemas/EventId'
        eventTime:
          $ref: '#/components/schemas/dateTime'
        category:
          description: Category of the Event (example, Billing Events, Security Events etc)
          type: string
          example: Security
        type:
          description: Type of the Event
          type: string
          example: Sim Fraud
        severity:
          $ref: '#/components/schemas/EventSeverity'
        status:
          $ref: '#/components/schemas/EventStatus'
        statusReason:
          type: string
          description: Additional Reasoning about status/status change.
        description:
          description: Description about the Event
          type: string
          example: IMEI change, TAC change, minimal change in data consumption.
        eventTypeDescription:
          description: Description about the Event type.
          type: string
          example: Detected anomalous communication(s).
        notes:
          description: Notes entered by a human user while taking an action on Event.
          type: string
        iccid:
          $ref: '#/components/schemas/iccid'
        imsi:
          $ref: '#/components/schemas/imsi'
        deviceProfileId:
          $ref: '#/components/schemas/deviceProfileId'
        productId:
          description: Product Id associated with the device.
          type: integer
          format: int32
          example: 41
        eventConfigId:
          type: integer
          description: Event Config Id
          example: 134242
        lastActionTime:
          $ref: '#/components/schemas/dateTime'
        lastActionUser:
          description: User who took some action on this Event.
          type: string
          format: email
          example: john.doe@example.com
        eventSource:
          type: string
          description: Source system of this Event
          example: Security Center
        context:
          type: object
          description: Context of Event. This is specific to each type of Event.
          additionalProperties: true
        deviceIp:
          $ref: '#/components/schemas/ip'
        devicePort:
          $ref: '#/components/schemas/port'
        serverIp:
          $ref: '#/components/schemas/ip'
        serverPort:
          $ref: '#/components/schemas/port'
        serverFqdn:
          $ref: '#/components/schemas/domain'
        deviceName:
          description: Name of the device.
          type: string
          maxLength: 30
          example: Lawn Mower 007
        eventTypeId:
          description: Event Type Id
          type: integer
          example: 5
        severityId:
          description: Severity Id. Lower values means higher severity.
          type: integer
          example: 5
        confidenceLevel:
          description: >-
            Indicates the system's certainty about the accuracy of the detected
            event.
          type: string
          example: 85
        threatClass:
          description: Categorizes the type of threat.
          type: string
          example: APT
        threatLevel:
          description: Shows the severity of the identified threat.
          type: integer
          example: 100
        threatDiagnostic:
          description: Provides detailed analysis and detection information of the threat.
          type: string
          example: >-
            The threat diagnostic identifies unusual login attempts from
            multiple locations.
        protectionLevel:
          description: This column will store the protection level with possible values.
          type: string
          example: Essential, Aggressive, Comprehensive.
        requestId:
          description: This column will store the request ID.
          type: string
          example: REQ201043380628
        deviceGroups:
          type: array
          items:
            $ref: '#/components/schemas/EventDeviceGroup'
        apnNames:
          type: array
          items:
            type: string
          description: Access Point Names (APN) associated with this event.
          example: [ "apn1", "apn2" ]
        apnTypes:
          type: array
          items:
            type: string
          description: Types of Access Point Names (APN) associated with this event.
          example: [ "type2", "type1" ]
        imei:
          type: string
          description: Current International Mobile Equipment Identity of the device.
          example: "867157040972691"
        prevImei:
          type: string
          description: Previous International Mobile Equipment Identity of the device (sim misuse).
          example: "867157040972690"
        deviceType:
          type: string
          description: Type of the device.
          example: "smartphone"
        country:
          type: string
          description: Country associated with the device location.
          example: "US"
        postalCode:
          type: string
          description: Postal code associated with the device location.
          example: "94105"
        postalTown:
          type: string
          description: Postal town associated with the device location.
          example: "San Francisco"
    EventConfig:
      type: object
      properties:
        id:
          type: integer
          description: Event Config Id
          example: 134242
        eventTypeId:
          description: Event Type Id
          type: integer
          example: 10
        type:
          description: Event Type
          type: string
          example: Traffic Spike
        detectionState:
          type: string
          enum:
            - DISMISSING
            - ACTIVE_FOR_ALL_DEVICES
            - MULTIPLE_STATES
        suppressionConfig:
          type: array
          items:
            $ref: '#/components/schemas/EventSuppressionConfig'
        lastModifiedBy:
          description: Last modified user
          type: string
          example: abc.xyz@aeris.com
        lastModifiedTime:
          $ref: '#/components/schemas/dateTime'
    EventConfigActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
        - type: object
          properties:
            suppressionPeriodType:
              $ref: '#/components/schemas/EventConfigSuppressionPeriodType'
            suppressionPeriodStart:
              $ref: '#/components/schemas/dateTime'
            suppressionPeriodEnd:
              $ref: '#/components/schemas/dateTime'
    EventActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
        - type: object
          properties:
            occurrence:
              type: integer
              format: int64
    EventSuppressionConfig:
      allOf:
        - type: object
          properties:
            id:
              description: Event suppression config Id
              type: integer
              format: int64
        - $ref: '#/components/schemas/EventSuppressionConfigBase'
        - type: object
          properties:
            eventConfigId:
              type: integer
              description: Event config Id
              example: 134242
            detectionState:
              type: string
            dismissPastEvents:
              type: boolean
            lastModifiedBy:
              description: Last modified user
              type: string
              example: abc.xyz@aeris.com
            lastModifiedTime:
              $ref: '#/components/schemas/dateTime'
    EventSuppressionConfigCreateRequest:
      allOf:
        - $ref: '#/components/schemas/EventSuppressionConfigBase'
        - type: object
          properties:
            dismissPastEvents:
              type: boolean
    EventSuppressionConfigUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/EventSuppressionConfigBase'
    EventSuppressionConfigBase:
      type: object
      properties:
        name:
          description: Name of the event suppression config
          type: string
          example: Dismiss Truck events
        description:
          description: Description of the event suppression config
          type: string
          example: This config is for dismissing all truck events
        config:
          type: array
          items:
            $ref: '#/components/schemas/ConfigItem'
        suppressionTargetDevices:
          $ref: '#/components/schemas/EventSuppressionTargetDevices'
        suppressionMatchingTraffic:
          type: array
          items:
            $ref: '#/components/schemas/EventSuppressionMatchingTraffic'
        suppressionPeriodType:
          $ref: '#/components/schemas/EventConfigSuppressionPeriodType'
        suppressionPeriodStart:
          $ref: '#/components/schemas/dateTime'
        suppressionPeriodEnd:
          $ref: '#/components/schemas/dateTime'
        comment:
          description: Comment for the suppression config
          type: string
          example: Just for truck
    ConfigItem:
      type: object
      properties:
        name:
          type: string
          description: Name of the configuration field.
          example: Minimum Threshold
        value:
          type: string
          description: Value of the configuration field.
          example: 1024
    EventSuppressionTargetDevices:
      type: object
      properties:
        iccid:
          type: array
          description: List of Integrated Circuit Card Identifier of the device.
          items:
            type: string
          example:
            - 891004234814455936
            - 891004234814455937
      required:
        - iccid
    EventSuppressionMatchingTraffic:
      type: object
      properties:
        serverIp:
          type: array
          description: List of IP Addresses
          items:
            type: string
          example:
            - 172.16.1.2
            - 172.16.1.3
        serverPort:
          type: array
          description: List of Port numbers
          items:
            type: string
            example:
              - 8080
              - 9922
        serverFqdn:
          type: array
          description: List of server fqdn
          items:
            type: string
          example:
            - example.com
            - anotherexample.com
        imei:
          type: array
          description: List of International Mobile Equipment Identity of the device, only applicable to SIM Misuse
          items:
            type: string
          example:
            - 86715704097269
            - 86715704097260
        numberOfPortsScanned:
          type: array
          description: Number of ports scanned, only applicable to Port Scan
          items:
            type: string
          example:
            - 6
            - 10
        targetScannedHosts:
          type: array
          description: IP subnet of scanned hosts, only applicable to Address Scan
          items:
            type: string
          example:
            - 10.0.2.0/24
    EventActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
        - type: object
          properties:
            occurrence:
              type: integer
              format: int64
    EventConfigActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    EventPolicyActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    EventPolicyActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
    PagedEventPolicyActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/EventPolicyActivityLog'
    PagedEventsTable:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Event'
    PagedEventConfigsTable:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/EventConfig'
    PagedEventConfigActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/EventConfigActivityLog"
    PagedEventActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/EventActivityLog"
    EventsQueryRequest:
      type: object
      properties:
        imsi:
          $ref: '#/components/schemas/imsi'
        iccid:
          $ref: '#/components/schemas/iccid'
        msisdn:
          $ref: '#/components/schemas/msisdn'
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/EventStatus'
        types:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/EventCategory'
        confidentLevel:
          type: integer
        threatLevel:
          type: integer
        threatClass:
          type: string
        threatDiagnostic:
          type: string
        deviceIp:
          $ref: '#/components/schemas/ip'
        endpointIp:
          $ref: '#/components/schemas/ip'
        endpointPort:
          $ref: '#/components/schemas/port'
        matchingProtectionLevels:
          type: array
          items:
            $ref: '#/components/schemas/malwareProtectionLevel'
        fqdn:
          $ref: '#/components/schemas/endpointFQDN'
        requestId:
          type: string
        deviceGroupIds:
          type: array
          items:
            type: integer
            format: int32
          description: Device Group Ids
        apnNames:
          type: array
          items:
            type: string
          description: Filter by APN names. All specified values must match (AND logic).
          example: [ "apn1", "apn2" ]
        apnTypes:
          type: array
          items:
            type: string
          description: Filter by APN types. All specified values must match (AND logic).
          example: [ "type1", "type2" ]
        imei:
          type: string
          description: Filter by device IMEI.
          example: "867157040972691"
        deviceType:
          type: string
          description: Filter by device type.
          example: "smartphone"
        countries:
          type: array
          items:
            type: string
            description: Country name.
            example: "United States"
          description: Filter by countries of device location (multi-value, OR logic).
          example: [ "United States", "Germany" ]
        postalCode:
          type: string
          description: Filter by postal code of device location.
          example: "94105"
        postalTown:
          type: string
          description: Filter by postal town of device location.
          example: "San Francisco"
    EventsMetricsRequest:
      allOf:
        - $ref: '#/components/schemas/EventsQueryRequest'
        - type: object
          properties:
            interval:
              type: string
              description: Time interval in ISO8601 duration format (e.g. P1D for daily, PT1H for hourly)
              example: PT1H
            dimensions:
              type: string
              description: Comma-separated list of dimensions
              example: type,status
            metrics:
              type: string
              description: >-
                Comma-separated list of metrics. use cnt__<field> to get count
                aggregate.
              example: cnt__event_id
    EventsUpdateRequest:
      type: object
      description: Object representing an event update request.
      properties:
        status:
          description: Status of the Event
          type: string
          example: Saved For Review
          enum:
            - New
            - Saved For Review
            - In Process
            - Resolved
            - Dismissed
          x-enum-varnames:
            - New
            - SavedForReview
            - InProcess
            - Resolved
            - Dismissed
        notes:
          description: Notes entered by a human user while taking an action on event.
          type: string
          example: Acknowledging the event. Starting investigation of IMEI change.
        reason:
          description: Additional Reasoning about status/status change.
          type: string
          example: False Positive
        email:
          type: string
          format: email
          description: Email id of the user
        requestId:
          description: This column will store the request ID.
          type: string
          example: REQ201043380628
    EventsBulkUpdateRequest:
      allOf:
        - type: object
          properties:
            eventIds:
              type: array
              items:
                type: string
                description: Event Id
                example: v1_1652823856823_6b71e284b63a527caa6296a66e9fdd0c
                maxLength: 128
                minLength: 1
        - $ref: '#/components/schemas/EventsUpdateRequest'
    AggregateEventSecurityItem:
      description: Aggregate Event Security Item
      type: string
      example: Malicious Endpoint
      enum:
        - Unclassified
        - Address Scan
        - Malicious IP
        - New IP
        - New Port
        - Port Scan
        - SIM Misuse
        - TCP Bad Flags
        - TCP Max Flows
        - Traffic Spike
        - Malicious Endpoint
        - Botnet and C&C
        - Cryptocurrency
        - Data Exfiltration
        - Suspicious Endpoint
        - Phishing
        - Ransomware
        - Devices located according to expectations
        - Non IoT devices in use
        - Unencrypted data flow to private apps
        - Unencrypted data flow to public apps
        - Use of untrusted DNS servers
        - Data Sovereignty
        - Devices communicating using VPN
        - Non compliant communication - OFAC
        - Public applications
        - Removable devices in use
        - Blocked Flows
        - Devices utilizing private APN
        - Devices utilizing internet APN
        - "Anomalous Mobility Event: Moving Outside a Location List"
        - "Anomalous Mobility Event: Impossible Mobility"
        - High Frequency Reconnect
        - High Cell Disconnect Rate
      x-enum-varnames:
        - Unclassified
        - AddressScan
        - MaliciousIP
        - NewIP
        - NewPort
        - PortScan
        - SIMMisuse
        - TCPBadFlags
        - TCPMaxFlows
        - TrafficSpike
        - MaliciousEndpoint
        - BotnetAndCnC
        - Cryptocurrency
        - DataExfiltration
        - SuspiciousEndpoint
        - Phishing
        - Ransomware
        - DevicesLocatedAccordingToExpectations
        - NonIoTDevicesInUse
        - UnencryptedDataFlowToPrivateApps
        - UnencryptedDataFlowToPublicApps
        - UseOfUntrustedDNSServers
        - DataSovereignty
        - DevicesCommunicatingUsingVPN
        - NonCompliantCommunicationOFAC
        - PublicApplications
        - RemovableDevicesInUse
        - BlockedFlows
        - DevicesUtilizingPrivateAPN
        - DevicesUtilizingInternetAPN
        - AnomalousMobilityEventMovingOutsideLocationList
        - AnomalousMobilityEventImpossibleMobility
        - HighFrequencyReconnect
        - HighCellDisconnectRate
    AggregateEventAssessedSeverity:
      description: Aggregate Event Severity
      type: string
      example: High
      enum:
        - Critical
        - High
        - Medium
        - Low
    AggregateEventRiskCategory:
      description: Aggregate Event Category
      type: string
      example: "Device Security: Anomalous"
      enum:
        - "Device Security: Anomalous"
        - "Device Security: Suspicious"
        - "Device Security: Malicious"
        - "Inventory and Control of Devices"
        - "Data Protection"
        - "Network Security"
        - "Application Security"
        - "Device Security: Traffic"
    AggregatedEventsQueryRequest:
      type: object
      properties:
        securityItems:
          type: array
          items:
            $ref: '#/components/schemas/AggregateEventSecurityItem'
        assessedSeverities:
          type: array
          items:
            $ref: '#/components/schemas/AggregateEventAssessedSeverity'
        riskCategories:
          type: array
          items:
            $ref: '#/components/schemas/AggregateEventRiskCategory'

    ##### Summary/Metrics
    Field:
      type: object
      properties:
        name:
          description: The field name.
          type: string
        type:
          description: The data type of the field.
          type: string
          enum:
            - BOOLEAN
            - DATE
            - TIMESTAMP
            - STRING
            - INTEGER
            - FLOAT
            - DOUBLE
            - ARRAY
      required:
        - name
        - type
    PagedSummaryTable:
      allOf:
        - type: object
          properties:
            lastEvaluatedDate:
              type: string
        - $ref: '#/components/schemas/Pagination'
        - $ref: '#/components/schemas/PagedSummaryTableData'
    PagedSummaryTableData:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/SummaryDataSchema'
        data:
          $ref: '#/components/schemas/SummaryDataRows'
    SummaryDataSchema:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
    SummaryDataRows:
      type: array
      items:
        type: array
        items: { }

    ##### Flow Aggregate Metrics (Data Transactions / Data Volume / DNS / Destination Endpoints / IP Flows)
    AccountDailyMetric:
      type: string
      description: Supported daily metric names.
      enum:
        - unique_endpoint_ip_count
        - unique_endpoint_fqdn_count
        - avg_mo_data_bytes_per_transaction
        - avg_mt_data_bytes_per_transaction
        - imei_change_event_count
        - public_dns_query_count
        - private_dns_query_count
        - total_mo_data_bytes
        - total_mt_data_bytes
    AccountDailyMetricsRequest:
      type: object
      required:
        - metrics
      properties:
        metrics:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AccountDailyMetric'
          example:
            - unique_endpoint_ip_count
            - public_dns_query_count
            - total_mo_data_bytes
            - total_mt_data_bytes

    ##### Deep Forensics — request schemas

    DeviceFlowFilter:
      type: object
      description: >-
        Filter parameters for device-scoped flow aggregate queries.
        `iccid` is required to scope the query to a single device.
      required:
        - iccid
      properties:
        iccid:
          type: string
          description: ICCID of the device to scope this query to.
          example: '99987240680301008462'
        destinationFqdn:
          type: string
          description: Filter by destination server FQDN (partial match).
          example: 'eicar.host'
        destinationIp:
          type: string
          description: Filter by destination server IP address.
          example: '103.126.211.51'
        applicationProtocol:
          type: string
          description: Filter by application-layer protocol (e.g. HTTPS, DNS, ICMP).
          example: 'HTTPS'
        serverPort:
          type: integer
          description: Filter by destination server port number.
          example: 443
        networkProtocol:
          type: array
          description: Filter by one or more network transport protocols.
          items:
            type: string
            enum: [ TCP, UDP, ICMP ]
          example: [ TCP, UDP ]

    DeviceFlowTableRequest:
      $ref: '#/components/schemas/DeviceFlowFilter'

    DeviceDnsFilter:
      allOf:
        - $ref: '#/components/schemas/DeviceFlowFilter'
        - type: object
          properties:
            isPublicDns:
              type: boolean
              description: >-
                When `true`, returns only public DNS queries. When `false`,
                returns only private DNS queries. Omit to return both.
            domainHosts:
              type: array
              maxItems: 1000
              items:
                type: string
              description: >-
                List of DNS server FQDNs or IPs to match against. When
                `domainHostsOperation` is omitted, defaults to `in` (include).
              example: [ 'dns.google', '1.1.1.1', '8.8.8.8' ]
            domainHostsOperation:
              type: string
              enum: [ in, ni ]
              default: in
              description: >-
                `in` — return only queries to hosts in the `domainHosts` list.
                `ni` — exclude queries to those hosts. Defaults to `in` when
                omitted.

    MetricGroup:
      type: string
      description: >-
        Selects which group of metrics to retrieve for the `/devices/flow-aggregates/metrics/search` endpoint.
        Each group maps to a fixed set of response fields:

        `DATA_TRANSACTIONS` — `avgMoDataBytes`, `avgMtDataBytes`.

        `DATA_VOLUME` — `sumMoDataBytes`, `sumMtDataBytes`.

        `DNS_QUERIES` — `privateOccurrences`, `publicOccurrences`.
        DNS filter fields apply.

        `DESTINATION_ENDPOINTS` — `uniqueServerIpCount`.

        `IP_FLOWS` — `occurrences`.
        IP-flow filter fields apply.
      enum:
        - DATA_TRANSACTIONS
        - DATA_VOLUME
        - DNS_QUERIES
        - DESTINATION_ENDPOINTS
        - IP_FLOWS

    DeviceMetricsChartRequest:
      allOf:
        - $ref: '#/components/schemas/DeviceDnsFilter'
        - type: object
          required:
            - interval
            - metricGroup
          properties:
            interval:
              type: string
              description: Time bucket size in ISO 8601 duration format. Only `PT1H` is currently supported.
              example: PT1H
            metricGroup:
              $ref: '#/components/schemas/MetricGroup'
            sourceIp:
              type: string
              description: >-
                Filter by source (device) IP address.
                Valid only for the `IP_FLOWS` metric group; a `400` is returned if
                used with any other group.
            sourcePort:
              type: integer
              description: >-
                Filter by source (device) port number.
                Valid only for the `IP_FLOWS` metric group; a `400` is returned if
                used with any other group.
            destinationPort:
              type: integer
              description: >-
                Filter by destination server port number.
                Valid only for the `IP_FLOWS` metric group; a `400` is returned if
                used with any other group.

    DnsQueriesTableRequest:
      $ref: '#/components/schemas/DeviceDnsFilter'

    DeviceIpFlowFilter:
      type: object
      description: >-
        Filter parameters for device-scoped IP Flow Metrics queries.
        `iccid` is required to scope the query to a single device.
      required:
        - iccid
      properties:
        iccid:
          type: string
          description: ICCID of the device to scope this query to.
          example: '99987240680301008462'
        destinationFqdn:
          type: string
          description: Filter by destination server FQDN.
        destinationIp:
          type: string
          description: Filter by destination server IP address.
        sourceIp:
          type: string
          description: Filter by source (device) IP address.
        sourcePort:
          type: integer
          description: Filter by source (device) port number.
        applicationProtocol:
          type: string
          description: Filter by application-layer protocol.
        destinationPort:
          type: integer
          description: Filter by destination server port number.
        networkProtocol:
          type: array
          description: Filter by one or more network transport protocols.
          items:
            type: string
            enum: [ TCP, UDP, ICMP ]
          example: [ TCP, UDP ]

    ##### Deep Forensics — response schemas

    DeepForensicsPagedBase:
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching records across all pages.
        offset:
          type: integer
        limit:
          type: integer

    DeviceMetricsChartResponse:
      type: object
      description: Response for the device metrics chart endpoint. Contains all matching time-series rows; no pagination.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DeviceMetricsChartRow'

    DeviceMetricsChartRow:
      type: object
      description: >-
        One time-bucket row in the device metrics chart response. Only the fields
        corresponding to the requested `metrics` are populated; others are omitted.
      properties:
        eventHour:
          type: string
          format: date-time
          description: Start of the time bucket (UTC).
        avgMoDataBytes:
          type: number
          format: double
          nullable: true
          description: Average mobile-originated data bytes per transaction.
        avgMtDataBytes:
          type: number
          format: double
          nullable: true
          description: Average mobile-terminated data bytes per transaction.
        sumMoDataBytes:
          type: integer
          format: int64
          nullable: true
          description: Total mobile-originated data bytes in the time bucket.
        sumMtDataBytes:
          type: integer
          format: int64
          nullable: true
          description: Total mobile-terminated data bytes in the time bucket.
        uniqueServerIpCount:
          type: integer
          nullable: true
          description: Count of unique destination server IPs in the time bucket.
        privateOccurrences:
          type: integer
          nullable: true
          description: Count of private DNS queries in the time bucket.
        publicOccurrences:
          type: integer
          nullable: true
          description: Count of public DNS queries in the time bucket.
        occurrences:
          type: integer
          nullable: true
          description: Count of IP flow events in the time bucket.

    FlowAggregatesTableRow:
      type: object
      description: >-
        Per-destination endpoint aggregate row, used by the Flow Aggregates table.
      properties:
        serverFqdn:
          type: string
          nullable: true
        serverIp:
          type: string
        applicationProtocol:
          type: string
        serverPort:
          type: integer
          nullable: true
        networkProtocol:
          type: string
        occurrences:
          type: integer
          format: int64
          description: Number of unique connection occurrences to this destination endpoint.
        sumMoDataBytes:
          type: integer
          format: int64
        sumMtDataBytes:
          type: integer
          format: int64
        sumDataBytes:
          type: integer
          format: int64

    PagedFlowAggregatesTable:
      allOf:
        - $ref: '#/components/schemas/DeepForensicsPagedBase'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/FlowAggregatesTableRow'

    DnsQueriesTableRow:
      type: object
      properties:
        serverFqdn:
          type: string
          nullable: true
        serverIp:
          type: string
        applicationProtocol:
          type: string
        serverPort:
          type: integer
          nullable: true
        isPrivateIp:
          type: boolean
          description: True when the DNS server IP is a private/RFC-1918 address.
        networkProtocol:
          type: string
        occurrences:
          type: integer
          format: int64
        sumMoDataBytes:
          type: integer
          format: int64
        sumMtDataBytes:
          type: integer
          format: int64
        sumDataBytes:
          type: integer
          format: int64

    PagedDnsQueriesTable:
      allOf:
        - $ref: '#/components/schemas/DeepForensicsPagedBase'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/DnsQueriesTableRow'

    IpFlowMetricsTableRow:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        serverFqdn:
          type: string
          nullable: true
        serverIp:
          type: string
        deviceIp:
          type: string
        devicePort:
          type: integer
          nullable: true
        serverPort:
          type: integer
          nullable: true
        networkProtocol:
          type: string
        applicationProtocol:
          type: string
        sumMoDataBytes:
          type: integer
          format: int64
        sumMtDataBytes:
          type: integer
          format: int64
        sumDataBytes:
          type: integer
          format: int64
        occurrences:
          type: integer

    PagedIpFlowMetricsTable:
      allOf:
        - $ref: '#/components/schemas/DeepForensicsPagedBase'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/IpFlowMetricsTableRow'

    ##### Devices & DeviceGroups
    deviceGroupId:
      description: Device Group ID.
      type: integer
      format: int64
    deviceId:
      description: Internal Device ID.
      type: integer
      format: int32
      example: 10407778
      minimum: 0
    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
    DeviceImeiChange:
      type: object
      properties:
        deviceId:
          $ref: '#/components/schemas/deviceId'
        iccid:
          $ref: '#/components/schemas/iccid'
        imei:
          $ref: '#/components/schemas/imei'
        previousImei:
          $ref: '#/components/schemas/imei'
        changeTime:
          $ref: '#/components/schemas/dateTime'
        deviceType:
          description: Device type info derived from IMEI/TAC.
          type: string
          example: Modem
        deviceBrand:
          description: Device brand info derived from IMEI/TAC.
          type: string
          example: Apple
        deviceModel:
          description: Device model derived info from IMEI/TAC.
          type: string
          example: iPhone 7
      required:
        - iccid
        - imei
        - previousImei
        - changeTime
    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
    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'
    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
    DeviceGroupType:
      type: string
      enum:
        - REPORTING
        - ENFORCEMENT
    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
    DeviceGroupInfo:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        colorCode:
          type: string
        deviceGroupType:
          type: string
    DeviceGroup:
      allOf:
        - type: object
          properties:
            id:
              type: integer
        - $ref: '#/components/schemas/DeviceGroupBase'
    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
    DeviceGroupCreateRequest:
      allOf:
        - $ref: '#/components/schemas/DeviceGroupResourceBase'
        - type: object
          properties:
            deviceGroupType:
              $ref: "#/components/schemas/DeviceGroupType"
    DeviceGroupUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/DeviceGroupResourceBase'
    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
    DeviceGroupActivityLog:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        userId:
          type: string
        activity:
          type: string
        target:
          type: string
        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'
    PagedDeviceImeiChanges:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              description: Array of IMEI change events
              items:
                $ref: '#/components/schemas/DeviceImeiChange'
    PagedDeviceGroupActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/DeviceGroupActivityLog"
    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' ]

    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
    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'
    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
    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'
    DeviceGroupActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'

    ##### Activity Logs
    BaseActivityLogQueryRequest:
      type: object
      properties:
        activity:
          type: string
        target:
          type: string
        userId:
          type: string
    BaseActivityLog:
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/dateTime'
        activity:
          type: string
        target:
          type: string
        userId:
          type: string

    ##### Enforcement (Applications/Protection Policies/Enforcement Rules)
    applicationId:
      description: Application identifier
      type: integer
      format: int64
      example: 10407
    ApplicationBase:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        protocols:
          type: array
          items:
            type: string
            example: TCP
          example: [ TCP, UDP ]
        endpoints:
          type: array
          items:
            type: string
            example: "10.104.17.101"
        endpointFQDNs:
          type: array
          items:
            $ref: "#/components/schemas/endpointFQDN"
        ports:
          type: array
          items:
            type: string
            example: 8080
    ApplicationCreateRequest:
      allOf:
        - $ref: '#/components/schemas/ApplicationBase'
    ApplicationUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/ApplicationBase'
    ApplicationsQueryRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 180
        endpoints:
          type: array
          items:
            type: string
        endpointFQDN:
          $ref: "#/components/schemas/endpointFQDN"
        ports:
          type: array
          items:
            type: string
        protocols:
          type: array
          items:
            type: string
        enforcementRuleId:
          type: integer
        enforcementRuleName:
          type: string
    PagedApplications:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Application'
    Application:
      allOf:
        - $ref: '#/components/schemas/ApplicationBase'
        - type: object
          properties:
            id:
              $ref: '#/components/schemas/applicationId'
            status:
              type: string
            createdBy:
              type: string
            createdTime:
              type: string
              format: date-time
            updatedBy:
              type: string
            updatedTime:
              type: string
              format: date-time
    ApplicationActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    ApplicationActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
    PagedApplicationActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/ApplicationActivityLog"

    protectionPolicyId:
      description: Protection Policy identifier
      type: integer
      format: int64
      example: 21091
    ProtectionPolicyBase:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        enforcementType:
          type: string
          description: "Enforcement type applied to this protection policy, can be ALLOWED_TRAFFIC or BLOCKED_TRAFFIC"
          enum:
            - ALLOWED_TRAFFIC
            - BLOCKED_TRAFFIC
          example: "ALLOWED_TRAFFIC"
        protocols:
          type: array
          items:
            type: string
            example: TCP
          example: [ TCP, UDP ]
        endpoints:
          type: array
          items:
            type: string
            example: "10.104.17.101"
        endpointFQDNs:
          type: array
          items:
            $ref: "#/components/schemas/endpointFQDN"
        ports:
          type: array
          items:
            type: string
            example: 8080
    ProtectionPolicyCreateRequest:
      allOf:
        - $ref: '#/components/schemas/ProtectionPolicyBase'
    ProtectionPolicyUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/ProtectionPolicyBase'
    ProtectionPoliciesQueryRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 180
        endpoints:
          type: array
          items:
            type: string
        enforcementType:
          type: string
        endpointFQDN:
          $ref: "#/components/schemas/endpointFQDN"
        ports:
          type: array
          items:
            type: string
        protocols:
          type: array
          items:
            type: string
        enforcementRuleId:
          type: integer
        enforcementRuleName:
          type: string
    PagedProtectionPolicies:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ProtectionPolicy'
    ProtectionPolicy:
      allOf:
        - $ref: '#/components/schemas/ProtectionPolicyBase'
        - type: object
          properties:
            id:
              $ref: '#/components/schemas/protectionPolicyId'
            status:
              type: string
            createdBy:
              type: string
            createdTime:
              type: string
              format: date-time
            updatedBy:
              type: string
            updatedTime:
              type: string
              format: date-time
    ProtectionPolicyActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    ProtectionPolicyActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
    PagedProtectionPolicyActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/ProtectionPolicyActivityLog"

    ##### Event Policies
    EventPolicyCreateResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ID of the newly created event policy
          example: 42
    EventPolicyCreateRequest:
      type: object
      required:
        - name
        - deviceGroupIds
        - eventTypeIds
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the event policy
          example: My Fleet Policy
        description:
          type: string
          description: Optional description
          example: Policy for monitoring anomalous mobility on fleet devices
        deviceGroupIds:
          type: array
          minItems: 1
          description: IDs of the device groups this policy applies to. At least one device group is required.
          items:
            type: integer
            format: int64
        eventTypeIds:
          type: array
          minItems: 1
          description: IDs of the event types (alert_types) to watch. At least one event type is required.
          items:
            type: integer
    EventPolicyUpdateRequest:
      type: object
      required:
        - name
        - deviceGroupIds
        - eventTypeIds
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the event policy
          example: My Fleet Policy
        description:
          type: string
          description: Optional description
        deviceGroupIds:
          type: array
          minItems: 1
          description: IDs of the device groups this policy applies to. At least one device group is required.
          items:
            type: integer
            format: int64
        eventTypeIds:
          type: array
          minItems: 1
          description: IDs of the event types to watch. At least one event type is required.
          items:
            type: integer
    EventPolicySearchRequest:
      type: object
      properties:
        name:
          type: string
          description: Filter by policy name (partial match, case-insensitive)
          example: fleet
        deviceGroupIds:
          type: array
          description: Filter — return policies that include ANY of these device group IDs
          items:
            type: integer
            format: int64
        eventTypeIds:
          type: array
          description: Filter — return policies that include ANY of these event type IDs
          items:
            type: integer
    EventPolicyResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Event policy ID
          example: 1
        accountId:
          type: integer
          format: int32
          description: Account ID
          example: 10407
        name:
          type: string
          description: Name of the event policy
          example: My Fleet Policy
        description:
          type: string
          description: Optional description
        deviceGroupIds:
          type: array
          description: IDs of the associated device groups
          items:
            type: integer
            format: int64
        eventTypeIds:
          type: array
          description: IDs of the watched event types
          items:
            type: integer
        createdBy:
          type: string
          description: User who created the policy
          example: john.doe@example.com
        createdTime:
          $ref: '#/components/schemas/dateTime'
        lastModifiedBy:
          type: string
          description: User who last modified the policy
          example: jane.doe@example.com
        lastModifiedTime:
          $ref: '#/components/schemas/dateTime'
    EventPolicySummaryResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Event policy ID
          example: 1
        accountId:
          type: integer
          format: int32
          description: Account ID
          example: 10407
        name:
          type: string
          description: Name of the event policy
          example: My Fleet Policy
        description:
          type: string
          description: Optional description
        deviceGroupIds:
          type: array
          description: IDs of the associated device groups
          items:
            type: integer
            format: int64
        eventTypeIds:
          type: array
          description: IDs of the watched event types
          items:
            type: integer
        createdBy:
          type: string
          example: john.doe@example.com
        createdTime:
          $ref: '#/components/schemas/dateTime'
        lastModifiedBy:
          type: string
          example: jane.doe@example.com
        lastModifiedTime:
          $ref: '#/components/schemas/dateTime'
    PagedEventPoliciesTable:
      type: object
      properties:
        page:
          type: integer
          example: 0
          description: Current page number (0-based)
        size:
          type: integer
          example: 20
          description: Page size
        totalPages:
          type: integer
          example: 5
          description: Total number of pages
        totalElements:
          type: integer
          format: int64
          example: 100
          description: Total number of elements
        content:
          type: array
          items:
            $ref: '#/components/schemas/EventPolicySummaryResponse'

    enforcementRuleId:
      description: Enforcement Rule identifier
      type: integer
      format: int64
      example: 5102010
    malwareProtectionLevel:
      type: string
      enum:
        - NONE
        - ESSENTIAL
        - AGGRESSIVE
        - COMPREHENSIVE
    enforcementRuleStatus:
      type: string
      enum:
        - ACTIVATED
        - DEACTIVATED
    EnforcementRuleUpdateRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        apn:
          type: string
        malwareProtectionLevel:
          $ref: '#/components/schemas/malwareProtectionLevel'
        applications:
          type: array
          items:
            $ref: '#/components/schemas/applicationId'
        protectionPolicies:
          type: array
          items:
            $ref: '#/components/schemas/protectionPolicyId'
        deviceGroupId:
          $ref: '#/components/schemas/deviceGroupId'
        forceReconnect:
          type: boolean
          description: Force devices reconnect - Kill switch
          default: false
        serviceConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/ServiceConfigurationRequest'
        editMode:
          type: boolean
          description: >-
            When this flag is on, user could edit the policy related fields such as (Applications, Protection Policies, Malware Protection) 
            for ACTIVE/ENFORCED Enforcement Rules
          default: false
      required:
        - name
        - apn
        - malwareProtectionLevel
        - applications
        - protectionPolicies
    EnforcementRuleCreateRequest:
      allOf:
        - $ref: '#/components/schemas/EnforcementRuleUpdateRequest'
        - type: object
          properties:
            enforce:
              type: boolean
              description: The enforcement rule should be enforced immediately after creation
              default: false
    EnforcementRulesQueryRequest:
      properties:
        name:
          type: string
        description:
          type: string
        deviceGroups:
          type: array
          items:
            $ref: '#/components/schemas/deviceGroupId'
        apns:
          type: array
          items:
            type: string
        malwareProtectionLevel:
          type: array
          items:
            $ref: '#/components/schemas/malwareProtectionLevel'
        status:
          type: array
          items:
            $ref: '#/components/schemas/enforcementRuleStatus'
        applications:
          type: array
          items:
            $ref: '#/components/schemas/applicationId'
        protectionPolicies:
          type: array
          items:
            $ref: '#/components/schemas/protectionPolicyId'
    EnforcementRuleBase:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/enforcementRuleId'
        name:
          type: string
        status:
          type: string
        apn:
          type: string
    PagedEnforcementRules:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/EnforcementRule'
    EnforcementRule:
      allOf:
        - $ref: '#/components/schemas/EnforcementRuleBase'
        - type: object
          properties:
            malwareProtectionLevel:
              $ref: '#/components/schemas/malwareProtectionLevel'
            applications:
              type: array
              items:
                $ref: '#/components/schemas/applicationId'
            protectionPolicies:
              type: array
              items:
                $ref: '#/components/schemas/protectionPolicyId'
            deviceGroupId:
              $ref: '#/components/schemas/deviceGroupId'
            forceReconnect:
              type: boolean
              description: Force devices reconnect - Kill switch
            serviceConfigurations:
              type: array
              items:
                $ref: '#/components/schemas/ServiceConfiguration'
            createdBy:
              type: string
            createdTime:
              type: string
              format: date-time
            updatedBy:
              type: string
            updatedTime:
              type: string
              format: date-time
    EnforcementRuleActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    EnforcementRuleActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
        - type: object
          properties:
            error:
              type: string
    ServiceConfigurationRequest:
      type: object
      description: Service configuration input for create/update
      properties:
        serviceConfigurationId:
          type: integer
          format: int64
          description: Present only on update to identify an existing config. Null/absent for new.
        serviceConfigurationType:
          type: string
          description: Type of configuration e.g. SPLIT_BILLING, RATE_LIMIT
        name:
          type: string
        description:
          type: string
          maxLength: 500
          description: Optional details/description for this service configuration.
        config:
          type: object
          additionalProperties: true
          description: Type-specific configuration payload (generic JSON)
        applicationIds:
          type: array
          items:
            type: integer
            format: int64
          description: Application IDs this configuration is bound to
      required:
        - serviceConfigurationType
        - name
        - config
    ServiceConfiguration:
      type: object
      description: Service configuration in responses (includes server-generated fields)
      properties:
        serviceConfigurationId:
          type: integer
          format: int64
        serviceConfigurationType:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        config:
          type: object
          additionalProperties: true
        applicationIds:
          type: array
          items:
            type: integer
            format: int64
    PagedEnforcementRuleActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/EnforcementRuleActivityLog"

    ##### Location Lists
    LocationListType:
      description: Type of the location list
      type: string
      enum:
        - GENERAL
        - PER_IMSI
    LocationListEntry:
      type: object
      properties:
        id:
          type: integer
          format: int64
          nullable: true
        imsi:
          $ref: '#/components/schemas/imsi'
        apn:
          type: string
          description: Access Point Name
          maxLength: 100
          example: internet.provider.com
        cellId:
          type: string
          description: Cell identifier
          maxLength: 50
          example: "12345"
        country:
          type: string
          description: Country name
          maxLength: 100
          example: United States
        postalTown:
          type: string
          description: Postal town
          maxLength: 100
          example: San Jose
        postalCode:
          type: string
          description: Postal code
          maxLength: 20
          example: "95134"
        latitude:
          type: number
          description: Latitude coordinate
          example: 37.38748
        longitude:
          type: number
          description: Longitude coordinate
          example: -121.92978
        mcc:
          type: integer
          description: Mobile Country Code
          example: 310
        mnc:
          type: integer
          description: Mobile Network Code
          example: 260
        lac:
          type: integer
          description: Location Area Code
          example: 1234
        effectiveStartTs:
          type: string
          description: Effective start timestamp
          example: "2025-01-01T00:00:00Z"
    LocationListResourceBase:
      type: object
      properties:
        name:
          type: string
          description: Name of the location list
          maxLength: 255
          minLength: 1
          example: "Allowed Cell Towers"
        description:
          type: string
          description: Description of the location list
          maxLength: 2048
          example: "Cell towers authorized for fleet vehicles"
        listType:
          $ref: "#/components/schemas/LocationListType"
        entries:
          type: array
          items:
            $ref: "#/components/schemas/LocationListEntry"
        deviceGroupIds:
          type: array
          description: IDs of device groups associated with this location list
          items:
            type: integer
    LocationListCreateRequest:
      allOf:
        - $ref: '#/components/schemas/LocationListResourceBase'
        - type: object
          required:
            - name
            - listType
    LocationListUpdateRequest:
      allOf:
        - $ref: '#/components/schemas/LocationListResourceBase'
        - type: object
          required:
            - name
            - listType
    LocationList:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        listType:
          $ref: "#/components/schemas/LocationListType"
        entries:
          type: array
          items:
            $ref: "#/components/schemas/LocationListEntry"
        entryCount:
          type: integer
          description: Total number of entries in the location list
        deviceGroupIds:
          type: array
          items:
            type: integer
        createdBy:
          type: string
        createdTime:
          type: string
          format: date-time
        updatedBy:
          type: string
        updatedTime:
          type: string
          format: date-time
    LocationListSummary:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        listType:
          $ref: "#/components/schemas/LocationListType"
        entryCount:
          type: integer
        deviceGroupIds:
          type: array
          items:
            type: integer
        createdBy:
          type: string
        createdTime:
          type: string
          format: date-time
        updatedBy:
          type: string
        updatedTime:
          type: string
          format: date-time
    LocationListQueryRequest:
      type: object
      properties:
        name:
          type: string
          description: Filter by location list name (partial match)
        listTypes:
          type: array
          description: Filter by location list types
          items:
            $ref: "#/components/schemas/LocationListType"
        deviceGroupIds:
          type: array
          description: Filter by associated device group IDs
          items:
            type: integer
    PagedLocationLists:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/LocationListSummary'
    LocationListActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    LocationListActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
    PagedLocationListActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/LocationListActivityLog"
    ServiceConfigurationActivityLogQuery:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLogQueryRequest'
    ServiceConfigurationActivityLog:
      allOf:
        - $ref: '#/components/schemas/BaseActivityLog'
    PagedServiceConfigurationActivityLog:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/ServiceConfigurationActivityLog"
    LocationListSuggestionRequest:
      type: object
      required:
        - deviceGroupIds
        - listType
        - effectiveStartTs
      properties:
        deviceGroupIds:
          type: array
          items:
            type: integer
        listType:
          $ref: '#/components/schemas/LocationListType'
        effectiveStartTs:
          type: object
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        country:
          type: string
          description: Optional filter by country
        postalTown:
          type: string
          description: Optional filter by city/town

    ##### Flows
    BlockedIPFlowsSearchRequest:
      type: object
      properties:
        flowType:
          type: string
        blockTypes:
          type: array
          items:
            type: string
        blockedBy:
          type: string
          description: Name of the enforcement rule that blocked the flow
        destinationIp:
          type: string
        destinationPorts:
          type: array
          items:
            type: string
        networkProtocols:
          type: array
          items:
            type: string
        protocols:
          type: array
          items:
            type: string
        enforcementRule:
          type: string
        iccid:
          type: string
        imsi:
          type: string
        msisdn:
          type: string
        sourceIp:
          type: string
        sourcePorts:
          type: array
          items:
            type: string
        destinationFQDN:
          type: string
        confidenceLevel:
          type: integer
        threatLevel:
          type: integer
        threatType:
          type: string
        threatClass:
          type: string
        threatDiagnostic:
          type: string
        deviceGroup:
          type: string
        servicePlan:
          type: string
        servicePlanId:
          type: string
        countryOfDevice:
          type: string
        mccMnc:
          type: string
        deviceType:
          type: string
    AllowedIPFlowsSearchRequest:
      type: object
      properties:
        flowType:
          type: string
        allowedBy:
          type: string
          description: Name of the application
        destinationIp:
          type: string
        destinationPorts:
          type: array
          items:
            type: string
        networkProtocols:
          type: array
          items:
            type: string
        protocols:
          type: array
          items:
            type: string
        enforcementRule:
          type: string
        iccid:
          $ref: "#/components/schemas/iccid"
        imsi:
          $ref: "#/components/schemas/imsi"
        msisdn:
          $ref: "#/components/schemas/msisdn"
        sourceIp:
          type: string
        sourcePorts:
          type: array
          items:
            type: string
        destinationFQDN:
          type: string
        deviceGroup:
          type: string
        allowedTypes:
          type: array
          items:
            type: string
        servicePlan:
          type: string
        servicePlanId:
          type: string
        countryOfDevice:
          type: string
        mccMnc:
          type: string
        deviceType:
          type: string
    BlockedFlowsSearchRequest:
      type: object
      properties:
        blockTypes:
          type: array
          items:
            type: string
        blockedBy:
          type: string
          description: Name of the enforcement rule that blocked the flow
        destinationIp:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        destinationPorts:
          type: array
          items:
            type: string
        networkProtocols:
          type: array
          items:
            type: string
        protocols:
          type: array
          items:
            type: string
        enforcementRule:
          type: string
        iccid:
          $ref: "#/components/schemas/iccid"
        imsi:
          $ref: "#/components/schemas/imsi"
        msisdn:
          $ref: "#/components/schemas/msisdn"
        sourceIp:
          type: string
        sourcePorts:
          type: array
          items:
            type: string
        destinationFQDN:
          type: string
        confidenceLevel:
          type: integer
        threatLevel:
          type: integer
        threatType:
          type: string
        threatClass:
          type: string
        threatDiagnostic:
          type: string
        deviceGroup:
          type: string
        servicePlan:
          type: string
        servicePlanId:
          type: string
        countryOfDevice:
          type: string
        mccMnc:
          type: string
        deviceType:
          type: string
    AllowedTrafficSearchRequest:
      type: object
      properties:
        allowedBy:
          type: string
          description: Name of the application
        destinationIp:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        destinationPorts:
          type: array
          items:
            type: string
        networkProtocols:
          type: array
          items:
            type: string
        protocols:
          type: array
          items:
            type: string
        enforcementRule:
          type: string
        iccid:
          $ref: "#/components/schemas/iccid"
        imsi:
          $ref: "#/components/schemas/imsi"
        msisdn:
          $ref: "#/components/schemas/msisdn"
        sourceIp:
          type: string
        sourcePorts:
          type: array
          items:
            type: string
        destinationFQDN:
          type: string
        deviceGroup:
          type: string
        allowedTypes:
          type: array
          items:
            type: string
        servicePlan:
          type: string
        servicePlanId:
          type: string
        countryOfDevice:
          type: string
        mccMnc:
          type: string
        deviceType:
          type: string
    BlockedIPFlowData:
      type: object
      properties:
        flowType:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        destinationIp:
          type: string
        destinationFQDN:
          type: string
        blockedBy:
          type: string
          description: Name of the enforcement rule that blocked the flow
        blockedById:
          type: integer
          format: int64
        blockType:
          type: string
        destinationPort:
          type: string
        networkProtocol:
          type: string
        protocol:
          type: string
        enforcementRuleName:
          type: string
        enforcementRuleId:
          type: integer
          format: int64
        deviceGroup:
          $ref: "#/components/schemas/DeviceGroupInfo"
        iccid:
          $ref: "#/components/schemas/iccid"
        imsi:
          $ref: "#/components/schemas/imsi"
        msisdn:
          $ref: "#/components/schemas/msisdn"
        sourceIp:
          type: string
        sourcePort:
          type: string
        confidenceLevel:
          type: integer
        threatLevel:
          type: integer
        threatClass:
          type: string
        threatDiagnostic:
          type: string
        servicePlan:
          type: string
        servicePlanId:
          type: string
        countryOfDevice:
          type: string
        mccMnc:
          type: integer
          format: int64
        deviceType:
          type: string
    AllowedIPFlowData:
      type: object
      properties:
        flowType:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        allowedBy:
          type: string
        allowedType:
          type: string
        applicationId:
          type: integer
          format: int64
        destinationIp:
          type: string
        destinationFQDN:
          type: string
        destinationPort:
          type: string
        networkProtocol:
          type: string
        protocol:
          type: string
        enforcementRuleName:
          type: string
        enforcementRuleId:
          type: integer
          format: int64
        deviceGroup:
          $ref: "#/components/schemas/DeviceGroupInfo"
        iccid:
          $ref: "#/components/schemas/iccid"
        imsi:
          $ref: "#/components/schemas/imsi"
        msisdn:
          $ref: "#/components/schemas/msisdn"
        sourceIp:
          type: string
        sourcePort:
          type: string
        servicePlan:
          type: string
        servicePlanId:
          type: string
        countryOfDevice:
          type: string
        mccMnc:
          type: integer
          format: int64
        deviceType:
          type: string
    PagedFlows:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/BlockedIPFlowData'
                  - $ref: '#/components/schemas/AllowedIPFlowData'
                discriminator:
                  propertyName: flowType
                  mapping:
                    BLOCKED: '#/components/schemas/BlockedIPFlowData'
                    ALLOWED: '#/components/schemas/AllowedIPFlowData'
    PagedAllowedTraffic:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/AllowedTrafficData'
    AllowedTrafficData:
      type: object
      properties:
        isParentComponent:
          type: boolean
        parentAccountId:
          type: integer
          format: int64
        allowedBy:
          type: string
        allowedType:
          type: string
        applicationId:
          type: integer
          format: int64
        enforcementRules:
          type: integer
          format: int64
        lastActivity:
          type: string
          format: date-time
        totalFqdn:
          type: integer
          format: int64
        totalIp:
          type: integer
          format: int64
        totalEnforcementRule:
          type: integer
          format: int64
        flowCount:
          type: integer
          format: int64
        deviceCount:
          type: integer
          format: int64
        fromDevices:
          type: integer
          format: int64
        toDevices:
          type: integer
          format: int64
        flowsFromDevices:
          type: integer
          format: int64
        flowsToDevices:
          type: integer
          format: int64
        totalData:
          type: number
        usages:
          type: array
          items:
            $ref: '#/components/schemas/AllowedTrafficUsageDetail'
    AllowedTrafficUsageDetail:
      type: object
      properties:
        destinationIp:
          type: string
        destinationFQDN:
          type: string
        networkProtocol:
          type: string
        protocol:
          type: string
        port:
          type: string
        flowCount:
          type: integer
          format: int64
        deviceCount:
          type: integer
          format: int64
        fromDevices:
          type: integer
          format: int64
        toDevices:
          type: integer
          format: int64
        flowsToDevices:
          type: integer
          format: int64
        flowsFromDevices:
          type: integer
          format: int64
        totalData:
          type: number
    PagedBlockedFlows:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/BlockedFlowData'
    BlockedFlowData:
      type: object
      properties:
        isParentComponent:
          type: boolean
        parentAccountId:
          type: integer
          format: int64
        blockedById:
          type: integer
          format: int64
        enforcementRuleId:
          type: array
          items:
            type: integer
            format: int4
        blockedBy:
          type: string
        blockedType:
          type: string
        totalIp:
          type: integer
          format: int64
        totalFQDN:
          type: integer
          format: int64
        sessionAttempts:
          type: integer
          format: int64
        devicesCount:
          type: integer
          format: int64
        attemptsFromDevices:
          type: integer
          format: int64
        attemptsToDevices:
          type: integer
          format: int64
        totalFlowsUp:
          type: integer
          format: int64
        totalFlowsDown:
          type: integer
          format: int64
        blockedFlows:
          type: array
          items:
            $ref: '#/components/schemas/BlockedFlowDetail'
    BlockedFlowDetail:
      type: object
      properties:
        destinationFQDN:
          type: string
          example: dns.google
        ipAddresses:
          type: array
          items:
            type: string
            example: 1.1.1.1
        networkProtocol:
          type: string
          example: TCP
        protocol:
          type: string
          example: HTTPS
        port:
          type: string
          example: '80'
        sessionAttempts:
          type: integer
          example: 53
        blockedDevices:
          type: integer
          example: 222
        attemptTime:
          type: string
          format: date-time
          example: '2025-10-01T23:59:02Z'
        enforcementRule:
          type: string
        totalFlowsUp:
          type: integer
          format: int64
        totalFlowsDown:
          type: integer
          format: int64
        attemptsFromDevices:
          type: integer
          format: int64
        attemptsToDevices:
          type: integer
          format: int64
        confidenceLevel:
          type: integer
        threatLevel:
          type: integer
        threatClass:
          type: string
        threatDiagnostic:
          type: string

    ##### Security Reports
    SecurityReportAppendixRequest:
      title: SecurityReportAppendixRequest
      type: object
      required:
        - year
        - month
      properties:
        year:
          type: integer
          title: Year
        month:
          type: integer
          title: Month
        category:
          type: string
          title: Category
        security_item:
          type: string
          title: Security Item
        iccid:
          type: string
          title: Iccid
        imsi:
          type: string
          title: Imsi
        start_ts:
          type: string
          title: Start Ts
        end_ts:
          type: string
          title: End Ts
        device_location:
          type: string
          title: Device Location
        device_type:
          type: string
          title: Device Type
        network_protocol:
          type: string
          title: Network Protocol
        protocol:
          type: string
          title: Protocol
        unencrypted_protocol:
          type: string
          title: Unencrypted Protocol
        server_port:
          type: string
          title: Server Port
        endpoint_location:
          type: string
          title: Endpoint Location
        fqdn:
          type: string
          title: Fqdn
        dns_server_ip:
          type: string
          title: Dns Server Ip
        scanned_subnet_port:
          type: string
          title: Scanned Subnet Port
        apn:
          type: array
          title: Apn
          items:
            type: string
        apn_type:
          type: array
          title: Apn Type
          items:
            type: string
        device_group_id:
          items:
            type: string
          type: array
          title: Device Group Id
    SecurityReportAppendixTrigger:
      properties:
        request_by:
          type: string
          title: Request By
        account_name:
          type: string
          title: Account Name
      type: object
      title: SecurityReportAppendixTrigger
    PagedSecurityReportAppendix:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SecurityEventData'
    SecurityReportSummary:
      properties:
        total_low:
          type: integer
          title: Total Low
        total_medium:
          type: integer
          title: Total Medium
        total_high:
          type: integer
          title: Total High
        overall_severity:
          $ref: '#/components/schemas/Severity'
        summary_text:
          type: string
          title: Summary Text
        disclaimer:
          type: string
          title: Disclaimer
        disclaimer_no2:
          type: string
          title: Disclaimer No2
        sections:
          $ref: '#/components/schemas/SectionsSummary'
        device_activated_summary:
          title: Device Activated Summary
          type: array
          items:
            type: array
            minItems: 3
            maxItems: 3
            items: { }
        trend_low:
          $ref: '#/components/schemas/TrendData'
        trend_medium:
          $ref: '#/components/schemas/TrendData'
        trend_high:
          $ref: '#/components/schemas/TrendData'
      type: object
      required:
        - total_low
        - total_medium
        - total_high
        - overall_severity
        - summary_text
        - disclaimer
        - disclaimer_no2
        - sections
        - device_activated_summary
        - trend_low
        - trend_medium
        - trend_high
      title: SecurityReportSummary
    SecurityReportDetail:
      properties:
        sections:
          $ref: '#/components/schemas/SecurityReportSections'
        category:
          $ref: '#/components/schemas/SecurityReportCategory'
      type: object
      required:
        - sections
        - category
      title: SecurityReportDetail
    SecurityReportCategory:
      properties:
        inventory_control_devices:
          type: string
          title: Inventory Control Devices
        data_protection:
          type: string
          title: Data Protection
        net_work_security:
          type: string
          title: Net Work Security
        application_security:
          type: string
          title: Application Security
        device_security:
          type: string
          title: Device Security
      type: object
      required:
        - inventory_control_devices
        - data_protection
        - net_work_security
        - application_security
        - device_security
      title: Category
    SecurityReportSections:
      properties:
        inventory_control_devices:
          items:
            $ref: '#/components/schemas/SecurityReportSectionItem'
          type: array
          title: Inventory Control Devices
        data_protection:
          items:
            $ref: '#/components/schemas/SecurityReportSectionItem'
          type: array
          title: Data Protection
        net_work_security:
          items:
            $ref: '#/components/schemas/SecurityReportSectionItem'
          type: array
          title: Net Work Security
        application_security:
          items:
            $ref: '#/components/schemas/SecurityReportSectionItem'
          type: array
          title: Application Security
        device_security:
          items:
            $ref: '#/components/schemas/SecurityReportSectionItem'
          type: array
          title: Device Security
      type: object
      required:
        - inventory_control_devices
        - data_protection
        - net_work_security
        - application_security
        - device_security
      title: Sections
    SecurityReportSectionItem:
      properties:
        sec_no:
          type: string
          title: Sec No
        tds:
          items:
            $ref: '#/components/schemas/TdsItem'
          type: array
          title: Tds
        alert_type:
          type: string
          title: Event Type
      type: object
      required:
        - sec_no
        - tds
      title: SectionItem
    SecurityReportDeviceUsage:
      properties:
        total:
          type: integer
          title: Total
        data:
          items:
            items:
              $ref: '#/components/schemas/DeviceUsageData'
            type: array
          type: array
          title: Rows
      type: object
      required:
        - total
        - data
      title: DeviceUsageResponse
    SecurityReportEndpoint:
      properties:
        total:
          type: integer
          title: Total
        data:
          items:
            items:
              $ref: '#/components/schemas/EndpointData'
            type: array
          type: array
          title: Data
      type: object
      required:
        - total
        - data
      title: EndpointResponse
    SecurityEventData:
      type: object
      title: SecurityEventData
      properties:
        account_id:
          type: string
          title: Account Id
        report_date:
          type: string
          format: date
          title: Report Date
        security_item:
          type: string
          title: Security Item
        iccid:
          type: string
          title: Iccid
        category:
          type: string
          title: Category
        current_ts:
          type: string
          format: date-time
          title: Current Ts
        imsi:
          type: string
          title: Imsi
        device_location:
          type: string
          title: Device Location
        device_type:
          type: string
          title: Device Type
        network_protocol:
          type: string
          title: Network Protocol
        protocol:
          type: string
          title: Protocol
        server_port:
          type: string
          title: Server Port
        endpoint_location:
          type: string
          title: Endpoint Location
        fqdn:
          type: string
          title: Fqdn
        dns_server_ip:
          type: string
          title: Dns Server Ip
        scanned_subnet_port:
          type: string
          title: Scanned Subnet Port
        unencrypted_protocol:
          type: string
          title: Unencrypted Protocol
        occurrence_count:
          type: integer
          title: Occurrence Count
        apn:
          type: array
          title: Apn
          items:
            type: string
        apn_type:
          type: array
          title: Apn Type
          items:
            type: string
        device_groups:
          type: array
          title: Device Groups
          items:
            type: object
            properties:
              group_id:
                type: string
                title: Group Id
              name:
                type: string
                title: Name
              color_code:
                type: string
                title: Color Code
              device_assigning_type:
                type: string
                title: Device Assigning Type
      required:
        - account_id
        - report_date
        - security_item
        - iccid
        - category
        - current_ts
        - imsi
        - device_location
        - device_type
        - network_protocol
        - protocol
        - server_port
        - endpoint_location
        - fqdn
        - dns_server_ip
        - scanned_subnet_port
        - unencrypted_protocol
        - device_groups
    EndpointData:
      properties:
        endpoint_country:
          type: string
          title: Endpoint Country
        device_count:
          type: integer
          title: Device Count
        endpoint_count:
          type: integer
          title: Endpoint Count
        data_usage_bytes:
          type: integer
          title: Data Usage Bytes
        ip_flows:
          type: integer
          title: Ip Flows
      type: object
      required:
        - endpoint_country
        - device_count
        - endpoint_count
        - data_usage_bytes
        - ip_flows
      title: EndpointData
    DeviceUsageData:
      properties:
        active_devices:
          type: integer
          title: Active Devices
        device_country:
          type: string
          title: Device Country
        data_usage_bytes:
          type: integer
          title: Data Usage Bytes
      type: object
      required:
        - active_devices
        - device_country
        - data_usage_bytes
      title: DeviceUsageData
    Severity:
      type: string
      enum:
        - High
        - Medium
        - Low
      title: Severity
      example: High
    SectionsSummary:
      properties:
        application_security:
          $ref: '#/components/schemas/SectionSummary'
        data_protection:
          $ref: '#/components/schemas/SectionSummary'
        device_security:
          $ref: '#/components/schemas/SectionSummary'
        inventory_control_devices:
          $ref: '#/components/schemas/SectionSummary'
        net_work_security:
          $ref: '#/components/schemas/SectionSummary'
      type: object
      required:
        - application_security
        - data_protection
        - device_security
        - inventory_control_devices
        - net_work_security
      title: SectionsSummary
    SectionSummary:
      properties:
        high:
          type: integer
          title: High
        medium:
          type: integer
          title: Medium
        low:
          type: integer
          title: Low
        highest_severity:
          $ref: '#/components/schemas/Severity'
        recommended_action:
          type: string
          title: Recommended Action
      type: object
      required:
        - high
        - medium
        - low
        - highest_severity
        - recommended_action
      title: SectionSummary
    TdsItem:
      properties:
        content:
          type: string
          title: Content
        column:
          type: string
          title: Column
        direction:
          type: string
          title: Direction
        current_value:
          type: number
          title: Current Value
        previous_value:
          type: number
          title: Previous Value
      type: object
      required:
        - content
        - column
      title: TdsItem
    TrendData:
      properties:
        content:
          type: string
          title: Content
        direction:
          $ref: '#/components/schemas/TrendDirection'
        current_value:
          type: integer
          title: Current Value
        previous_value:
          type: integer
          title: Previous Value
      type: object
      required:
        - content
        - direction
        - current_value
        - previous_value
      title: TrendData
      description: Schema for a trend object.
    TrendDirection:
      type: string
      enum:
        - trend_up
        - trend_down
        - trend_flat
      title: TrendDirection

    ##### Rate Limiters
    ExternalRateLimiterCreateRequest:
      type: object
      required:
        - name
        - configs
      properties:
        name:
          type: string
          maxLength: 100
          description: Name of the rate limiter group.
        configs:
          type: array
          description: List of rate limiter configurations to create (one per limit type).
          items:
            $ref: '#/components/schemas/ExternalRateLimiterConfig'
    ExternalRateLimiterConfig:
      type: object
      required:
        - limitType
        - upstreamRate
        - upstreamBurstSize
        - downstreamRate
        - downstreamBurstSize
      properties:
        limitType:
          type: string
          description: The limit type.
          enum:
            - SESSION_LEVEL
            - AGGREGATE
        upstreamRate:
          type: integer
          format: int64
          description: Upstream rate in kbps.
        upstreamBurstSize:
          type: integer
          format: int64
          description: Upstream burst size in kbps.
        downstreamRate:
          type: integer
          format: int64
          description: Downstream rate in kbps.
        downstreamBurstSize:
          type: integer
          format: int64
          description: Downstream burst size in kbps.
    ExternalRateLimiterUpdateRequest:
      type: object
      required:
        - upstreamRate
        - upstreamBurstSize
        - downstreamRate
        - downstreamBurstSize
      properties:
        name:
          type: string
          maxLength: 100
          description: Name of the rate limiter.
        upstreamRate:
          type: integer
          format: int64
          description: Upstream rate in kbps.
        upstreamBurstSize:
          type: integer
          format: int64
          description: Upstream burst size in kbps.
        downstreamRate:
          type: integer
          format: int64
          description: Downstream rate in kbps.
        downstreamBurstSize:
          type: integer
          format: int64
          description: Downstream burst size in kbps.
    ExternalRateLimitersQueryRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
          description: Filter by name of the rate limiter.
        limitTypes:
          type: array
          items:
            type: string
          description: Filter by the limit type.
    PagedRateLimiters:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/RateLimiter'
    ExternalRateLimiterListResponse:
      type: object
      properties:
        rateLimiters:
          type: array
          items:
            $ref: '#/components/schemas/RateLimiter'
    RateLimiter:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The rate limiter ID.
        serviceConfigurationId:
          type: integer
          format: int64
          description: The linked service configuration ID.
        name:
          type: string
          description: Name of the rate limiter.
        limitType:
          type: string
          description: The limit type.
          enum:
            - SESSION_LEVEL
            - AGGREGATE
        upstreamRate:
          $ref: '#/components/schemas/upstreamRate'
        upstreamBurstSize:
          $ref: '#/components/schemas/upstreamBurstSize'
        downstreamRate:
          $ref: '#/components/schemas/downstreamRate'
        downstreamBurstSize:
          $ref: '#/components/schemas/downstreamBurstSize'
        createdBy:
          type: string
          description: The user who created the rate limiter.
        createdTime:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: The user who last updated the rate limiter.
        updatedTime:
          type: string
          format: date-time
    upstreamRate:
      type: integer
      format: int64
      minimum: 0
      description: Upstream rate in kbps.
    upstreamBurstSize:
      type: integer
      format: int64
      minimum: 0
      description: Upstream burst size in kbps.
    downstreamRate:
      type: integer
      format: int64
      minimum: 0
      description: Downstream rate in kbps.
    downstreamBurstSize:
      type: integer
      format: int64
      minimum: 0
      description: Downstream burst size in kbps.
  responses:
    '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.967
            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.967
            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.967
            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.967
            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.967
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '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.967
            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.967
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '409Configuration':
      description: Conflict — resource already exists or invalid state transition
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfigurationErrorResponse'
    '400Configuration':
      description: Bad Request — validation failure (RFC 7807)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfigurationErrorResponse'
          example:
            title: "Payload validation failed"
            status: 400
            correlationId: "c7f5a8b2-1234-5678-abcd-ef0123456789"
            errors:
              - field: "gatewayId"
                code: "VALIDATION_ERROR"
                message: "must be exactly 15 digits"
    '503Configuration':
      description: Service Unavailable — downstream dependency failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfigurationErrorResponse'