openapi: 3.0.3
info:
  title: ExtremeCloud IQ Account PacketCaptures 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: PacketCaptures
  description: Packet capture sessions in ExtremeCloud IQ
paths:
  /packetcaptures:
    get:
      tags:
      - PacketCaptures
      summary: List packet capture sessions
      operationId: listPacketCaptures
      description: List packet capture sessions with filters and pagination.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_list_packet_captures
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - name: searchString
        in: query
        description: The string to be searched in capture session name, interface name and device host name
        required: false
        schema:
          type: string
      - name: sortField
        in: query
        description: Sort field. Available values - NAME, START_TIME and STATUS
        required: false
        schema:
          type: string
          enum:
          - NAME
          - START_TIME
          - STATUS
      - $ref: '#/components/parameters/order'
      - name: fields
        in: query
        description: The packet capture fields to return
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/XiqPacketCaptureField'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedXiqPacketCapture'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    post:
      tags:
      - PacketCaptures
      summary: Create a new packet capture session
      operationId: createPacketCapture
      description: Create and start a new packet capture session with requested capture location and filter criteria.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_create_packet_capture
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XiqPacketCapture'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqPacketCapture'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /packetcaptures/{id}:
    get:
      tags:
      - PacketCaptures
      summary: Get a packet capture session by ID
      operationId: getPacketCapture
      description: Get a packet capture session by id.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_packet_capture
      parameters:
      - $ref: '#/components/parameters/id'
      - name: fields
        in: query
        description: The packet capture fields to return
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/XiqPacketCaptureField'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqPacketCapture'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    delete:
      tags:
      - PacketCaptures
      summary: Delete a packet capture session
      operationId: deletePacketCapture
      description: Delete an existing packet capture session and capture files by ID.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_delete_packet_capture
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /packetcaptures/{id}/:stop:
    post:
      tags:
      - PacketCaptures
      summary: Stop a packet capture session
      operationId: stopPacketCapture
      description: Stop an active packet capture session.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_stop_active_packet_capture
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XiqCaptureStopRequest'
        required: true
      responses:
        '200':
          description: OK
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /packetcaptures/{id}/:upload:
    post:
      tags:
      - PacketCaptures
      summary: Upload a packet capture session's capture files
      operationId: uploadPacketCaptureFiles
      description: Upload the capture files from a packet capture session, if files previously failed to be uploaded to XIQ cloud.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_upload_packet_captures_capture_files
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /packetcaptures/files:
    get:
      tags:
      - PacketCaptures
      summary: Get an AP packet capture file
      operationId: getPacketCaptureFile
      description: Get an AP packet capture file from XIQ cloud storage.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_packet_capture_file
      parameters:
      - name: cloudFileUrl
        in: query
        description: The packet capture file path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns requested packet capture file.
          content:
            application/octet-stream:
              schema:
                type: string
                description: Packet capture file
                format: binary
        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'
    page:
      name: page
      in: query
      description: Page number, min = 1
      required: false
      schema:
        minimum: 1
        type: integer
        format: int32
        default: 1
    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
    id:
      name: id
      in: path
      description: The unique identifier
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    XiqCaptureLocation:
      title: XiqCaptureLocation
      description: This represents the options for location packet capture.
      allOf:
      - type: object
        properties:
          direction:
            $ref: '#/components/schemas/XiqCaptureDirectionSelection'
          wired_interface:
            description: The name of the wired interface to capture. Set to ALL for all interfaces.
            $ref: '#/components/schemas/XiqCaptureWiredSelection'
          wired_filters:
            type: array
            description: The list of pre-defined wired filters for packet capture
            items:
              $ref: '#/components/schemas/XiqWiredFilterType'
          radio:
            description: The wireless radio to capture. Set to ALL for all radios.
            $ref: '#/components/schemas/XiqCaptureRadioSelection'
          wireless_band:
            description: The wireless band to capture. Set to ALL for all bands.
            $ref: '#/components/schemas/XiqCaptureBandSelection'
          wireless_filters:
            type: array
            description: The list of pre-defined wireless filters for packet capture
            items:
              $ref: '#/components/schemas/XiqWirelessFilterType'
      example:
        direction: Both
        wired_interface: ETH0
        wireless_band: 2.4GHZ
        wireless_filters:
        - MANAGEMENT
        - CONTROL
    XiqSerialNumber:
      type: object
      description: The globally unique serial number of the device being registered. The serial number is represented as a string.
      properties:
        ap_serial_number:
          type: string
          pattern: "^[\\p{Print}&&[^\t\n\r;:&\\p{Cntrl}'\"]]{1,16}$"
    XiqCloudSharkStorage:
      type: object
      title: XiqCloudSharkStorage
      description: The packet capture file name and URL in CloudShark.
      properties:
        file_name:
          type: string
        file_url:
          type: string
      example:
        file_name: 2023051105924UTC-241FBD8FEDC0-wifi0.pcap
        file_url: https://www.cloudshark.org/captures/f27d1494400c
    XiqPacketCapture:
      title: XiqPacketCapture
      description: This represents the packet capture session
      allOf:
      - $ref: '#/components/schemas/XiqCaptureIdentifier'
      - type: object
        properties:
          id:
            type: integer
            description: The unique identifier
            format: int64
          org_id:
            type: integer
            description: The organization identifier, valid when enabling HIQ feature
            format: int64
          name:
            description: The packet capture session name. If the name is null or empty, it will be auto generated.
            type: string
            pattern: ^[A-Z0-9.-_]{0,128}$
          duration:
            type: integer
            format: int32
            maximum: 604800
            minimum: 5
            description: An integer containing the set packet capture duration in seconds, from 5 to a maximum of 604800 seconds (1 week). If not manually stopped, packet capture continues until the specified duration is reached, or the platform-maximum file size of the AP is reached. If duration is set to 0 or unspecified, capture stops when platform-maximum size is reached.
          destination:
            $ref: '#/components/schemas/XiqDestinationType'
          filter:
            $ref: '#/components/schemas/XiqCaptureFilter'
          capture_if:
            $ref: '#/components/schemas/XiqCaptureLocation'
          start_time:
            type: string
            readOnly: true
            description: The packet capture start time
            format: date-time
          end_time:
            type: string
            readOnly: true
            description: The packet capture end time
            format: date-time
          status:
            readOnly: true
            description: The status of the packet capture session
            allOf:
            - $ref: '#/components/schemas/XiqPktCaptureStatus'
          cloud_storage:
            description: XIQ cloud storage location for the archive of all capture files in this capture session, if available.
            type: string
          results:
            type: array
            readOnly: true
            description: The list of packet capture results - a PacketCaptureResult for each device's interface
            items:
              $ref: '#/components/schemas/XiqCaptureResult'
    XiqDestinationType:
      title: XiqDestinationType
      type: string
      description: The destination for the packet capture files. CLOUD for XIQ cloud storage. CLOUD_SHARK for sending the capture files to CloudShark, in addition to XIQ cloud storage.
      enum:
      - CLOUD
      - CLOUD_SHARK
      example: CLOUD
    XiqSortOrder:
      type: string
      enum:
      - ASC
      - DESC
    XiqCaptureDirectionSelection:
      type: string
      title: XiqCaptureDirectionSelection
      description: The capture traffic direction
      enum:
      - OUT
      - IN
      - BOTH
      default: BOTH
      example: BOTH
    XiqPacketCaptureField:
      type: string
      enum:
      - ID
      - ORG_ID
      - NAME
      - CAPTURE_ID_TYPE
      - AP_SERIAL_NUMBER
      - DEVICE_IDS
      - LOCATION_ID
      - DURATION
      - DESTINATION
      - FILTER
      - CAPTURE_IF
      - START_TIME
      - END_TIME
      - STATUS
      - CLOUD_STORAGE
      - RESULTS
    XiqPktCaptureStatus:
      type: string
      title: XiqPktCaptureStatus
      description: The status of the overall packet capture session or a packet capture result on an AP device's interface.
      enum:
      - INITIAL
      - ACTIVE
      - SUCCESS
      - PARTIAL_SUCCESS
      - FAILED
      default: INITIAL
      example: ACTIVE
    XiqCaptureResult:
      title: XiqCaptureResult
      description: This represents the packet capture result on an AP's interface. A packet capture session may involve multiple APs on multiple interfaces.
      allOf:
      - type: object
        properties:
          id:
            type: integer
            description: The unique identifier
            format: int64
          start_time:
            type: string
            description: The packet capture start time
            format: date-time
          end_time:
            type: string
            description: The packet capture end time
            format: date-time
          org_id:
            type: integer
            description: The organization identifier, valid when enabling HIQ feature
            format: int64
          device_id:
            type: integer
            description: The device identifier
            format: int64
          interface:
            type: string
            description: The interface name such as "WIFI0", "WIFI1", "ETH0", etc.
          hostname:
            type: string
            description: The device host name such as "US-MIL-1"
          mac_address:
            type: string
            description: The device MAC address such as "AABBCC001122"
          location_id:
            type: integer
            description: The location ID
            format: int64
          locations:
            type: array
            description: The detailed location
            items:
              $ref: '#/components/schemas/XiqLocationLegend'
          status:
            description: The status of the packet capture result
            allOf:
            - $ref: '#/components/schemas/XiqPktCaptureStatus'
          error_message:
            type: string
            description: The error message (may be empty).
          storage:
            type: object
            description: The packet capture file storage
            properties:
              cloud_shark_storage:
                description: CloudShark file info when destination is CloudShark
                allOf:
                - $ref: '#/components/schemas/XiqCloudSharkStorage'
              cloud_storage:
                description: XIQ cloud storage location after a packet capture is completed.
                type: string
    XiqCaptureFilter:
      title: XiqCaptureFilter
      description: This represents the properties of filters used for the packet capture.
      allOf:
      - type: object
        properties:
          mac_addr:
            type: array
            items:
              type: string
            description: A string containing the client MAC address used for packet capturing.
          ip_addr:
            type: array
            items:
              type: string
            description: A string containing the client IP addresses used to filter the packets.
          protocol:
            $ref: '#/components/schemas/XiqPolicyRuleProtocolType'
          protocol_number:
            type: integer
            format: int32
            description: The protocol number if protocol is "USER_DEFINED".
          port:
            type: integer
            format: int32
            description: The port for packet capture
          vlan:
            type: string
            description: Specific vlan ids in a string, e.g. range "2-100"; single "3"; list "1,2,5,7,122"; mixed "2,4,5-10,19,29". If not specified, default is all VLANs.
          wlan:
            type: string
            description: A WLAN SSID. If not specified, default is all WLANs.
      example:
        mac_addr:
        - '...'
        - '...'
        ip_addr:
        - '...'
        - '...'
        protocol: any
        port: 12345
        vlan: 2,4,5-10
    XiqWirelessFilterType:
      type: string
      title: XiqWirelessFilterType
      description: Pre-defined filters for wireless packet captures.
      enum:
      - MANAGEMENT
      - CONTROL
      - DATA
      - EAPOL
      - BEACONS
      - PROBES
      example: DATA
    XiqErrorParams:
      type: object
      description: Error parameters
      properties:
        field:
          type: string
          description: The error field
        value:
          type: string
          description: The error value
    XiqLocationId:
      type: object
      description: The assigned location ID, it must be FLOOR type
      properties:
        location_id:
          type: integer
          format: int64
    XiqPolicyRuleProtocolType:
      type: string
      title: XiqPolicyRuleProtocolType
      description: Protocol type to filter by.
      enum:
      - ANY
      - USER_DEFINED
      - ICMP
      - ICMPV6
      - TCP
      - UDP
      - GRE
      - IPSEC_ESP
      - IPSEC_AH
      default: ANY
      example: ANY
    XiqDeviceIds:
      type: object
      description: The device ID list.
      properties:
        device_ids:
          type: array
          items:
            type: integer
            description: The device ID
            format: int64
    XiqCaptureWiredSelection:
      type: string
      title: XiqCaptureWiredSelection
      description: Wired interface to filter by.
      enum:
      - ALL
      - ETH0
      - ETH1
      - ETH2
      - ETH3
      example: ETH0
    PagedXiqPacketCapture:
      allOf:
      - $ref: '#/components/schemas/XiqPage'
      - type: object
        properties:
          data:
            type: array
            description: The data in the current page
            items:
              $ref: '#/components/schemas/XiqPacketCapture'
    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
    XiqCaptureStopRequest:
      title: XiqCaptureStopRequest
      description: This represents the request for stopping a packet capture session.
      properties:
        device_ids:
          type: array
          description: The IDs of the devices for which the active packet capture is to be stopped.  If empty, packet capture is to be stopped on all devices in this packet capture.
          items:
            type: integer
            description: The device ID
            format: int64
    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
    XiqCaptureIdentifier:
      type: object
      description: Identifier for AP device selections. APs can be selected using the AP serial number, a list of device numeric IDs or the location ID.
      required:
      - capture_id_type
      properties:
        capture_id_type:
          description: The capture identifier type for selecting the APs. Depending on the type, one of "AP_SERIAL_NUMBER", "DEVICE_IDS" and "LOCATION" must be provided.
          type: string
          enum:
          - AP_SERIAL_NUMBER
          - DEVICE_IDS
          - LOCATION
      anyOf:
      - $ref: '#/components/schemas/XiqSerialNumber'
      - $ref: '#/components/schemas/XiqDeviceIds'
      - $ref: '#/components/schemas/XiqLocationId'
      discriminator:
        propertyName: capture_id_type
        mapping:
          AP_SERIAL_NUMBER: '#/components/schemas/XiqSerialNumber'
          DEVICE_IDS: '#/components/schemas/XiqDeviceIds'
          LOCATION: '#/components/schemas/XiqLocationId'
    XiqWiredFilterType:
      type: string
      title: XiqWiredFilterType
      description: Pre-defined filters for wired packet captures.
      enum:
      - DHCP
      - RADIUS
      - LLDP
      - ARP
      - MDNS
      example: DHCP
    XiqCaptureBandSelection:
      type: string
      title: XiqCaptureBandSelection
      description: Wireless band to filter by.
      enum:
      - ALL
      - 2.4GHZ
      - 5GHZ
      - 6GHZ
      default: ALL
      example: 2.4GHZ
    XiqCaptureRadioSelection:
      type: string
      title: XiqCaptureRadioSelection
      description: Wireless radio type to filter by.
      enum:
      - ALL
      - RADIO1
      - RADIO2
      - RADIO3
      example: RADIO1
    XiqLocationLegend:
      type: object
      description: The simple location information
      properties:
        id:
          type: integer
          description: The location ID
          format: int64
        name:
          type: string
          description: The location name
  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