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


    The Aeris IoT Watchtower™ API provides access to resources such as real-time events, aggregated events, risk assessment reports, and device group operations.'
  termsOfService: https://www.aeris.com/services-terms-of-use/
  contact:
    email: support@aeris.net
    url: https://www.aeris.com/support/
  license:
    name: Aeris License
    url: https://www.aeris.com/services-terms-of-use/
  x-audience: external-public
servers:
- url: https://watchtower-api-prd.aeriscloud.com
security:
- oAuth2ClientCredentials: []
tags:
- name: Location Lists
  description: Endpoints for Location Lists
paths:
  /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'
components:
  schemas:
    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
    total:
      type: integer
      format: int64
      description: Total number of items available.
      example: 1
      minimum: 0
    LocationListEntry:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
          format: int64
        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'
    offset:
      description: Position in pagination.
      type: integer
      format: int32
      default: 0
      minimum: 0
    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
    limit:
      type: integer
      format: int32
      description: Number of items to retrieve (10000 max).
      minimum: 1
      maximum: 10000
      default: 20
    accountId:
      description: Account Id.
      type: integer
      format: int32
      example: 10407
      minimum: 0
    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
    LocationListUpdateRequest:
      allOf:
      - $ref: '#/components/schemas/LocationListResourceBase'
      - type: object
        required:
        - name
        - listType
    LocationListType:
      description: Type of the location list
      type: string
      enum:
      - GENERAL
      - PER_IMSI
    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
    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
    LocationListCreateRequest:
      allOf:
      - $ref: '#/components/schemas/LocationListResourceBase'
      - type: object
        required:
        - name
        - listType
    Pagination:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/total'
        offset:
          $ref: '#/components/schemas/offset'
        limit:
          $ref: '#/components/schemas/limit'
    imsi:
      description: International Mobile Subscriber Identifier of the device.
      type: string
      maxLength: 15
      example: '310009133100012'
    PagedLocationLists:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/LocationListSummary'
  responses:
    '429':
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 429
            message: 'Rate Limit Exceeded (XX) for clientId: XXXXXX. Please retry after XXX seconds'
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '401':
      description: Not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '403':
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '400':
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '404':
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not found
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '413':
      description: Requested data too large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 413
            message: Requested data too large. Please use /watchtower/v1/.../export for requesting larger amounts of data
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
  parameters:
    sort:
      name: sort
      in: query
      description: Use <b>sort=comma-separated-fields[:asc|desc]</b> to sort the result.
      example: deviceId,updateTime:desc
      schema:
        type: string
    accountId:
      name: X-Watchtower-Account-Id
      in: header
      description: Account Id
      required: true
      schema:
        $ref: '#/components/schemas/accountId'
      example: 1002000010
    offset:
      name: offset
      in: query
      description: The position in pagination. Specifies the starting row offset into the result set returned. For example, if the page size (limit) is 10, then to select the second page, pass the offset as 10 to retrieve items 11 to 20.<br><br> Search parameters must be consistent across pages.
      schema:
        $ref: '#/components/schemas/offset'
    locationListId:
      name: locationListId
      in: path
      required: true
      description: The ID of the location list
      schema:
        type: integer
        format: int64
    authorization:
      name: Authorization
      in: header
      description: Bearer Token for authentication
      required: true
      schema:
        type: string
        pattern: ^Bearer [A-Za-z0-9-._~+/]+=*$
      example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...
    limit:
      name: limit
      in: query
      description: The number of items to retrieve per page (10000 max).
      schema:
        $ref: '#/components/schemas/limit'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: This API uses OAuth 2 with the Client Credentials flow.
      flows:
        clientCredentials:
          tokenUrl: /watchtower/v1/auth/token
          scopes: {}