openapi: 3.0.3
info:
  title: ExtremeCloud IQ Account Application API
  description: 'ExtremeCloud IQ™ API allows customers and partners to create solutions for the management, monitoring, and provisioning

    of any ExtremeCloud IQ™ environment.


    All related resources and documentation are available at [ExtremeCloud IQ Developer Portal](https://developer.extremecloudiq.com/).

    Please check [Get Started and Tutorial](https://developer.extremecloudiq.com/documentation/) to understand how to use the APIs.


    Get the [latest OpenAPI definition](https://github.com/extremenetworks/ExtremeCloudIQ-OpenAPI/blob/main/xcloudiq-openapi.yaml)

    from [ExtremeCloud IQ OpenAPI GitHub repository](https://github.com/extremenetworks/ExtremeCloudIQ-OpenAPI).


    Please have a valid [ExtremeCloud IQ](https://extremecloudiq.com/) account before getting started.

    If you don''t have one, please [register a new account](https://www.extremenetworks.com/cloud-networking/).'
  termsOfService: https://www.extremenetworks.com/company/legal/terms-of-use/
  contact:
    name: Extreme Networks Support
    url: https://www.extremenetworks.com/support
    email: support@extremenetworks.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 25.9.0-36
servers:
- url: https://api.extremecloudiq.com
  description: ExtremeCloud IQ REST API Server
tags:
- name: Application
  description: Application management and application metrics
paths:
  /applications:
    get:
      tags:
      - Application
      summary: List the applications
      description: List a page of applications by filter.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_list_the_applications
      operationId: listApplications
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - name: sortField
        in: query
        description: The sort field
        required: false
        schema:
          $ref: '#/components/schemas/XiqApplicationSortField'
      - $ref: '#/components/parameters/order'
      - name: name
        in: query
        description: Application Name
        required: false
        schema:
          type: string
      - name: detectionProtocol
        in: query
        description: Application Detection Protocol, only for custom Application
        required: false
        schema:
          $ref: '#/components/schemas/XiqApplicationDetectionProtocol'
      - name: detectionType
        in: query
        description: Application Detection Type, only for custom Application
        required: false
        schema:
          $ref: '#/components/schemas/XiqApplicationDetectionType'
      - name: predefined
        in: query
        description: Flag to filter predefined or custom Application
        required: false
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedXiqApplication'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /applications/top{n}:
    get:
      tags:
      - Application
      summary: List the TopN applications
      description: List the TopN applications by usage.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_list_top_n_applications_usage
      operationId: listTopApplicationsUsage
      parameters:
      - $ref: '#/components/parameters/n'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/XiqTopApplicationsUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /applications/{id}/clients/top{n}:
    get:
      tags:
      - Application
      summary: List the TopN clients for a application
      description: List the TopN clients by usage for a specific application.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_list_top_n_clients_usage_for_one_application
      operationId: listApplicationTopClientsUsage
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/n'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/XiqApplicationTopClientsUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /applications/grid:
    post:
      tags:
      - Application
      summary: List application usage summary
      description: Returns a paginated list of application usage summaries with support for search, filter, and sort.
      operationId: listApplicationUsageSummary
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - name: sort_field
        in: query
        description: Field to sort by (e.g., usage, percentage_usage, clients, users)
        required: false
        schema:
          type: string
          enum:
          - usage
          - percentage_usage
          - clients
          - users
          - application_name
          - category_name
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/async'
      - name: search
        in: query
        description: Search term for application or category name
        required: false
        schema:
          type: string
      requestBody:
        description: Filters for category and number-based columns
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                category_name:
                  type: array
                  items:
                    type: string
                  description: Filter by one or more category (application group) names
                application_name:
                  type: array
                  items:
                    type: string
                  description: Filter by one or more application names
                site_ids:
                  description: List of site IDs to filter the applications grid
                  type: array
                  items:
                    type: integer
                    format: int64
                number_filters:
                  type: array
                  description: 'The number-based column filters available. Available columns: usage, percentageUsage, clients, users.

                    '
                  items:
                    $ref: '#/components/schemas/number_filter'
      responses:
        '200':
          description: A paginated list of application usage summaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedAppUsageSummary'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /applications/category_metadata:
    get:
      tags:
      - Application
      summary: List application categories and names
      description: Returns a list of unique application category names along with associated application names used in application usage data.
      operationId: listApplicationCategoriesAndNames
      responses:
        '200':
          description: Lists of application categories and application names
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      type: string
                      description: Application category name
                  applicationNames:
                    type: array
                    items:
                      type: string
                      description: Application name
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /applications/grid/export:
    post:
      tags:
      - Application
      summary: Export application usage summary
      description: Export the application usage summary grid as a CSV file.
      operationId: export_application_usage_to_csv
      parameters:
      - name: search
        in: query
        description: Search term for application or category name
        required: false
        schema:
          type: string
      - name: sort_field
        in: query
        description: Field to sort by (e.g., usage, percentage_usage, clients, users)
        required: false
        schema:
          type: string
          enum:
          - usage
          - percentage_usage
          - clients
          - users
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/async'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                category_name:
                  type: array
                  items:
                    type: string
                  description: Filter by one or more category (application group) names
                application_name:
                  type: array
                  items:
                    type: string
                  description: Filter by one or more application names
                site_ids:
                  description: List of site IDs to filter the applications grid
                  type: array
                  items:
                    type: integer
                    format: int64
                number_filters:
                  type: array
                  description: 'The number-based column filters available. Available columns: usage, percentage_usage, clients, users.

                    '
                  items:
                    $ref: '#/components/schemas/number_filter'
      responses:
        '202':
          description: Accepted - The request has been accepted for processing, but the processing has not been completed.
          headers:
            location:
              description: The URL to check the status or download the exported file
              schema:
                type: string
                format: uri
            retry-after:
              description: Time in seconds to wait before polling the status
              schema:
                type: integer
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
components:
  parameters:
    order:
      name: order
      in: query
      description: The sort order (ascending by default)
      required: false
      schema:
        $ref: '#/components/schemas/XiqSortOrder'
    startTime:
      name: startTime
      in: query
      description: The start time to query, epoch time in milliseconds since 1/1/1970
      required: true
      schema:
        type: integer
        format: int64
    page:
      name: page
      in: query
      description: Page number, min = 1
      required: false
      schema:
        minimum: 1
        type: integer
        format: int32
        default: 1
    async:
      in: query
      name: async
      description: Whether to enable async mode
      required: false
      schema:
        type: boolean
        default: false
    limit:
      name: limit
      in: query
      description: Page Size, min = 1, max = 100
      required: false
      schema:
        maximum: 100
        minimum: 1
        type: integer
        format: int32
        default: 10
    endTime:
      name: endTime
      in: query
      description: The end time to query, epoch time in milliseconds since 1/1/1970
      required: true
      schema:
        type: integer
        format: int64
    id:
      name: id
      in: path
      description: The unique identifier
      required: true
      schema:
        type: integer
        format: int64
    n:
      name: n
      in: path
      description: The TopN number
      required: true
      schema:
        maximum: 100
        minimum: 1
        type: integer
        format: int32
  schemas:
    XiqTopApplicationsUsage:
      type: object
      description: The Top N Applications Usage
      properties:
        id:
          type: integer
          description: The application ID
          format: int64
        name:
          type: string
          description: The application name
        clients:
          type: integer
          description: The associated unique client count
          format: int64
        users:
          type: integer
          description: The associated unique user count
          format: int64
        usage:
          type: integer
          description: The application usage
          format: int64
    XiqSortOrder:
      type: string
      enum:
      - ASC
      - DESC
    XiqApplicationDetectionProtocol:
      type: string
      enum:
      - HTTP
      - HTTPS
    PagedXiqApplication:
      allOf:
      - $ref: '#/components/schemas/XiqPage'
      - type: object
        properties:
          data:
            type: array
            description: The data in the current page
            items:
              $ref: '#/components/schemas/XiqApplication'
    XiqApplicationDetectionType:
      type: string
      enum:
      - HOST_NAME
      - SERVER_IP_ADDRESS
      - PORT_NUMBER
    XiqErrorParams:
      type: object
      description: Error parameters
      properties:
        field:
          type: string
          description: The error field
        value:
          type: string
          description: The error value
    number_filter:
      type: object
      description: If the filter type is between, only then min and max are to be used, else value is to be used.
      properties:
        column_name:
          description: The name of the column being filtered
          type: string
        filter_type:
          description: The type of number filter
          type: string
          enum:
          - eq
          - neq
          - gt
          - gte
          - lt
          - lte
          - bw
          - blank
          - notblank
        value:
          description: The value of the number
          type: integer
          format: int64
        min:
          description: The minimum value of the number
          type: integer
          format: int64
        max:
          description: The maximum value of the number
          type: integer
          format: int64
    XiqBaseEntity:
      required:
      - id
      - create_time
      - update_time
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier
          format: int64
        create_time:
          type: string
          description: The create time
          format: date-time
        update_time:
          type: string
          description: The last update time
          format: date-time
    XiqError:
      type: object
      properties:
        error_code:
          type: string
          description: The error code
        error_id:
          type: string
          description: The error ID for internal troubleshooting
        error_message:
          type: string
          description: The error detailed message
        error_message_code:
          type: string
          description: The error message code
        error_message_description:
          type: string
          description: The error message description
        error_params:
          $ref: '#/components/schemas/XiqErrorParams'
      required:
      - error_code
      - error_id
      - error_message
    RmAppUsageSummary:
      type: object
      properties:
        application_name:
          type: string
          description: Name of the application
        category_name:
          type: string
          description: Name of the application group or category
        usage:
          type: integer
          format: int64
          description: Total data usage in bytes for the application
        percentage_usage:
          type: number
          format: float
          description: Percentage of total traffic attributed to this application
        clients:
          type: integer
          description: Number of unique client devices that used the application
        users:
          type: integer
          description: Number of unique users associated with the application
    XiqPage:
      required:
      - count
      - page
      - total_count
      - total_pages
      type: object
      properties:
        page:
          type: integer
          description: The current page number
          format: int32
        count:
          type: integer
          description: The element count of the current page
          format: int32
        total_pages:
          type: integer
          description: The total page number based on request page size
          format: int32
        total_count:
          type: integer
          description: The total element count
          format: int64
    XiqApplication:
      allOf:
      - $ref: '#/components/schemas/XiqViqEntity'
      - type: object
        properties:
          name:
            type: string
            description: The application name.
          description:
            type: string
            description: The application description.
          predefined:
            type: boolean
            description: Flag to describe whether the application is predefined or customized.
          category_id:
            type: integer
            description: The category ID of application.
            format: int64
          category_name:
            type: string
            description: The category name of application.
          detection_rules:
            type: array
            description: The application detection rules.
            items:
              $ref: '#/components/schemas/XiqApplicationDetectionRule'
    XiqViqEntity:
      allOf:
      - $ref: '#/components/schemas/XiqBaseEntity'
      - type: object
        properties:
          org_id:
            type: integer
            description: The organization identifier, valid when enabling HIQ feature
            format: int64
        required:
        - org_id
    XiqApplicationSortField:
      type: string
      enum:
      - NAME
      - CATEGORY
    PagedAppUsageSummary:
      allOf:
      - $ref: '#/components/schemas/XiqPage'
      - type: object
        properties:
          data:
            type: array
            description: The data in the current page
            items:
              $ref: '#/components/schemas/RmAppUsageSummary'
    XiqApplicationTopClientsUsage:
      type: object
      description: The Top N Clients Usage per Application
      properties:
        application_id:
          type: integer
          description: The application ID
          format: int64
        client_id:
          type: integer
          description: The TOP N client ID
          format: int64
        client_mac_address:
          type: string
          description: The MAC address of TOP N client
        client_host_name:
          type: string
          description: The host name of TOP N client
        usage:
          type: integer
          description: The TOP N client usage
          format: int64
    XiqApplicationDetectionRule:
      type: object
      description: The Application Detection Rule
      properties:
        value:
          type: string
          description: The value of detection rule type.
        protocol:
          $ref: '#/components/schemas/XiqApplicationDetectionProtocol'
        type:
          $ref: '#/components/schemas/XiqApplicationDetectionType'
  responses:
    ErrorResponse:
      description: The generic ExtremeCloud IQ API error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/XiqError'
  securitySchemes:
    BearerAuth:
      type: http
      description: JSON Web Token (JWT) based authentication
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: API Reference
  url: https://extremecloudiq.com/api-docs/api-reference.html