Cisco Catalyst SD-WAN Troubleshooting Tools - Network Wide Path Insight API

openapi: 3.2.0
info:
  title: Monitoring and Troubleshooting Troubleshooting Tools - Network Wide Path Insight API
  description: "Includes API operations for the following:\n  Real-time monitoring\n  Accessing statistics APIs and statistics bulk APIs\n  Retrieving device state\n  Managing alarms and events"
  contact:
    email: vmanage@cisco.com
  license:
    name: Commercial License
    url: https://www.cisco.com/c/en/us/solutions/enterprise-networks/sd-wan/index.html
  version: 26.1.0+2026-01-06
  x-provenance:
    method: harvested
    authored_by: Cisco Catalyst SD-WAN
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 4,138 operations across 2,841 paths, published by Cisco as self-contained per-operation OpenAPI 3.1.0 fragments on the DevNet CDN and consolidated here into 13 documents. Ownership verified from info.contact vmanage@cisco.com and the Cisco license URL rather than from the fetch host.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/cisco-catalyst-sd-wan-26-1-api-guide/docs/
  - type: source
    url: https://developer.cisco.com/docs/sdwan/
servers:
- url: /dataservice
tags:
- name: Troubleshooting Tools - Network Wide Path Insight
paths:
  /stream/device/nwpi/exportTrace:
    get:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Export NWPI Trace Data
      operationId: exportTrace
      parameters:
      - name: traceId
        in: query
        description: trace id
        required: true
        schema:
          maximum: 262144
          minimum: 1
          type: integer
          format: int32
      - name: timestamp
        in: query
        description: start time
        required: true
        schema:
          maximum: 10000000000000
          minimum: 1
          type: integer
          format: int64
      - name: traceModel
        in: query
        description: traceModel
        schema:
          pattern: ^(SDWAN_MANUAL|SDWAN_AUTO_ON|SD_ROUTING_MANUAL)$
          type: string
        examples:
          Get manual traces:
            description: Get manual traces
            value: SDWAN_MANUAL
          Get auto on traces:
            description: Get auto on traces
            value: SDWAN_AUTO_ON
          Get sd-routing traces:
            description: Get sd-routing traces
            value: SD_ROUTING_MANUAL
      responses:
        '200':
          description: Success
          content:
            application/octet-stream:
              schema:
                type: object
              examples:
                Nwpi Trace Data File:
                  description: Nwpi Trace Data File
                  value: '{binary format response}'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      x-roles-required: Device Monitoring-read,Device Monitoring-write
  /stream/device/nwpi/importTrace:
    post:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Import Trace
      operationId: importTrace
      parameters:
      - name: newTraceName
        in: query
        schema:
          type: string
      - name: mode
        in: query
        description: mode
        schema:
          pattern: ^(SD-WAN|SD Routing)$
          type: string
        examples:
          default:
            description: default
          sdwan platform:
            description: sdwan platform
            value: SD-WAN
          sd-routing platform:
            description: sd-routing platform
            value: SD Routing
      requestBody:
        description: Trace Data File
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              $$ref: '#/components/schemas/ImportTraceRequest'
        required: true
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                  state:
                    type: boolean
                $$ref: '#/components/schemas/ImportTraceResponse'
              examples:
                Success Response:
                  description: Success Response
                  value:
                    state: true
                    msg: Trace imported successfully.
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /stream/device/nwpi/tasks/create:
    post:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Task Action - Create
      operationId: taskCreate
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              Create Trace Start Task with empty Duration:
                description: Create Trace Start Task with empty Duration
                value:
                  taskName: auto-on
                  events:
                  - sla-violation
                  - qos-congestion
                  sites:
                  - '100'
                  - '500'
                  duration: ''
              Create Trace Start Task with Duration:
                description: Create Trace Start Task with Duration
                value:
                  taskName: auto-on
                  events:
                  - sla-violation
                  - qos-congestion
                  sites:
                  - '100'
                  - '500'
                  duration: '1440'
              Create Trace Start Task without Duration:
                description: Create Trace Start Task without Duration
                value:
                  taskName: auto-on
                  events:
                  - sla-violation
                  - qos-congestion
                  sites:
                  - '100'
                  - '500'
              Create Trace Start Task with Event Extensions:
                description: Create Trace Start Task with Event Extensions
                value:
                  taskName: auto_on
                  events:
                  - qos-congestion
                  - sla-violation
                  - security-alert
                  - wan-loss
                  - tunnel-ipsec-anti-replay-drop
                  sites:
                  - '100'
                  - '500'
                  duration: 1440
                  qosCongestionExtensions:
                    applications:
                    - google-services
                    qosCongestionOccurrencesCount: 2
                    qosCongestionBurstInterval: 60
                    filters:
                    - application-in-event
                  slaViolationExtensions:
                    applications:
                    - rtp-video
                    slaViolationOccurrencesCount: 2
                    filters:
                    - application-in-event
                  securityAlertExtensions:
                    firewallDropRate: 10
                    utdIpsAlertGid: 1
                    utdIpsAlertSid: 49043
                    utdFileSha: 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
                    utdFileRetrospectiveSha: 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
                    securityAlertSubEvent:
                    - utd-ips-alert
                    - utd-file-reputation-alert
                    - utd-file-reputation-retrospective-alert
                    - firewall-drop
                    filters:
                    - source-ip-in-alert-event
                    - destination-ip-in-alert-event
                  wanLossExtensions:
                    wanLossRate: 30
                  ipsecAntiReplayDropExtensions:
                    ipsecAntiReplayDropRate: 30
              Create Task with Time Scheduled Traces:
                description: Create Task with Time Scheduled Traces
                value:
                  taskName: auto_on
                  duration: 1440
                  taskTimeZone: UTC+08:00
                  createdBy: admin
                  timeScheduledTraceExtensions:
                    traceSchedule:
                      recurDaysList:
                      - Monday
                      - Tuesday
                      - Wednesday
                      - Thursday
                      - Friday
                      - Saturday
                      - Sunday
                      traceActiveTimeList:
                      - traceStartTime: '10:00'
                        traceDuration: '60'
                      - traceStartTime: '15:00'
                        traceDuration: '60'
                    tracePayload:
                      source-site: '500'
                      local-drop-rate-threshold: 5
                      wan-drop-rate-threshold: 5
                      device-list:
                      - local-system-ip: 172.16.255.15
                        deviceId: 172.16.255.15
                        uuid: C8K-646ad78f-fee8-41f1-be58-2f9c5b82f2cf
                        version: 17.18.01.0.214177
                      vpn-list:
                      - '1'
                      - '100'
                      art-vis: 'true'
                      app-vis: 'true'
                      qos-mon: 'true'
                      te-mon: 'true'
                      source-site-version: '17.18'
                      traceModel: SDWAN_AUTO_ON
              Create Trace Start Task with Task Schedule Extensions:
                description: Create Trace Start Task with Task Schedule Extensions
                value:
                  taskName: auto_on
                  duration: 1440
                  events:
                  - sla-violation
                  - qos-congestion
                  sites:
                  - '500'
                  - '600'
                  taskTimeZone: UTC+08:00
                  taskScheduleExtensions:
                    recurDaysList:
                    - Monday
                    - Tuesday
                    - Wednesday
                    - Thursday
                    - Friday
                    - Saturday
                    - Sunday
                    taskActiveTimeList:
                    - taskActiveStartTime: '10:00'
                      taskActiveDuration: '3'
              Create Task with Time Scheduled Traces and Task Schedule Extensions:
                description: Create Task with Time Scheduled Traces and Task Schedule Extensions
                value:
                  taskName: auto_on
                  duration: 1440
                  events:
                  - sla-violation
                  - qos-congestion
                  sites:
                  - '500'
                  - '600'
                  taskTimeZone: UTC+08:00
                  createdBy: admin
                  taskScheduleExtensions:
                    recurDaysList:
                    - Monday
                    - Tuesday
                    - Wednesday
                    - Thursday
                    - Friday
                    - Saturday
                    - Sunday
                    taskActiveTimeList:
                    - taskActiveStartTime: '10:00'
                      taskActiveDuration: '3'
                  timeScheduledTraceExtensions:
                    traceSchedule:
                      recurDaysList:
                      - Monday
                      - Friday
                      traceActiveTimeList:
                      - traceStartTime: 09:00
                        traceDuration: '60'
                    tracePayload:
                      source-site: '500'
                      local-drop-rate-threshold: 5
                      wan-drop-rate-threshold: 5
                      device-list:
                      - local-system-ip: 172.16.255.15
                        deviceId: 172.16.255.15
                        uuid: C8K-646ad78f-fee8-41f1-be58-2f9c5b82f2cf
                        version: 17.18.01.0.214177
                      vpn-list:
                      - '1'
                      - '100'
                      art-vis: 'true'
                      app-vis: 'true'
                      qos-mon: 'true'
                      te-mon: 'true'
                      source-site-version: '17.18'
                      traceModel: SDWAN_AUTO_ON
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  action:
                    type: string
                  entry_time:
                    type: integer
                    format: int32
                  expire-time:
                    type: integer
                    format: int32
                  sites:
                    type: array
                    items:
                      type: string
                  state:
                    type: string
                  taskId:
                    type: integer
                    format: int32
                  taskName:
                    type: string
                description: Auto on task create schema for POST response
                $$ref: '#/components/schemas/TasksCreateResponsePayload'
              examples:
                Create task response:
                  description: Create task response
                  value:
                    action: success
                    sites:
                    - '100'
                    - '500'
                    taskId: 3
                    taskName: auto_on
                    entry_time: 1716795211822
                    expire-time: 1716881611822
                    state: active
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      x-roles-required: Device Monitoring-write
  /stream/device/nwpi/tasks/delete/{taskId}:
    delete:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Delete Auto On Task
      operationId: taskDelete
      parameters:
      - name: taskId
        in: path
        description: taskId
        required: true
        schema:
          pattern: ^[1-9][0-9]{0,5}$
          type: string
          example: '2'
      - name: taskStartTime
        in: query
        description: task start time
        schema:
          maximum: 10000000000000
          minimum: 1
          type: integer
          format: int64
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  action:
                    type: string
                  message:
                    type: object
                    properties:
                      duration:
                        type: string
                      entry_time:
                        type: integer
                        format: int64
                      events:
                        type: string
                      expire-time:
                        type: integer
                        format: int64
                      message:
                        type: string
                      sites:
                        type: string
                      state:
                        type: string
                      taskId:
                        type: integer
                        format: int32
                      taskName:
                        type: string
                      traces:
                        type: boolean
                    $$ref: '#/components/schemas/TasksDeleteResponsePayloadMessage'
                  taskId:
                    type: string
                description: Auto on task schema for DELETE response
                $$ref: '#/components/schemas/TasksDeleteResponsePayload'
              examples:
                Delete task response:
                  description: Delete task response
                  value:
                    action: success
                    taskId: '2'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      x-roles-required: Device Monitoring-write
  /stream/device/nwpi/tasks/stop/{taskId}:
    post:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Task Action - Stop
      operationId: taskStop
      parameters:
      - name: taskId
        in: path
        description: taskId
        required: true
        schema:
          type: string
          example: '2'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  action:
                    type: string
                  entry_time:
                    type: integer
                    format: int32
                  message:
                    type: string
                  state:
                    type: string
                  taskId:
                    type: string
                  taskName:
                    type: string
                description: Auto on task stop schema for POST response
                $$ref: '#/components/schemas/TasksStopResponsePayload'
              examples:
                Task stop response:
                  description: Task stop response
                  value:
                    action: success
                    taskId: 2
                    taskName: auto-on
                    state: finished
                    message: Task Stop initiated successfully (user stop)
                    startTime: 1716777834490
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      x-roles-required: Device Monitoring-write
  /stream/device/nwpi/tasks/taskHistory:
    get:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Get all the auto on tasks
      operationId: getTaskHistory
      parameters:
      - name: startTime
        in: query
        description: query start time
        schema:
          maximum: 10000000000000
          minimum: 1
          type: integer
          format: int64
      - name: endTime
        in: query
        description: query end time
        schema:
          maximum: 10000000000000
          minimum: 1
          type: integer
          format: int64
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        duration:
                          type: string
                        entry_time:
                          type: integer
                          format: int32
                        events:
                          type: array
                          items:
                            type: string
                        expire-time:
                          type: integer
                          format: int32
                        sites:
                          type: array
                          items:
                            type: string
                        state:
                          type: string
                        taskId:
                          type: integer
                          format: int32
                        taskName:
                          type: string
                        traces:
                          type: boolean
                        type:
                          type: string
                      $$ref: '#/components/schemas/TaskHistoryResponsePayloadData'
                description: Auto on task schema for GET response
                $$ref: '#/components/schemas/TaskHistoryResponsePayload'
              examples:
                Response for getting tasks:
                  description: Response for getting tasks
                  value:
                    header:
                      generatedOn: 1716795499234
                      viewKeys:
                        uniqueKey: []
                        preferenceKey: grid-nwpiTaskData
                      columns:
                      - title: Task Name
                        property: taskName
                        dataType: string
                      - title: Task ID
                        property: taskId
                        dataType: number
                      - title: Event(s)
                        property: events
                        dataType: array
                      - title: Site(s)
                        property: sites
                        dataType: array
                      - title: State
                        property: state
                        dataType: string
                      - title: Start Time
                        property: startTime
                        displayFormat: DD MMM YYYY h:mm:ss A z
                        inputFormat: unix-time
                        dataType: date
                      - title: Duration
                        property: duration
                        dataType: string
                      - title: Stop Time
                        property: stopTime
                        displayFormat: DD MMM YYYY h:mm:ss A z
                        inputFormat: unix-time
                        dataType: date
                      fields:
                      - property: taskName
                        dataType: string
                      - property: taskId
                        dataType: number
                      - property: events
                        dataType: array
                      - property: sites
                        dataType: array
                      - property: state
                        dataType: string
                      - property: startTime
                        dataType: date
                      - property: duration
                        dataType: string
                      - property: stopTime
                        dataType: date
                      - property: data
                        dataType: object
                    data:
                    - taskId: 4
                      taskName: auto_on
                      duration: '600'
                      events:
                      - qos-congestion
                      - sla-violation
                      sites:
                      - '100'
                      - '500'
                      sitesName:
                      - SITE_100
                      - SITE_500
                      stopTime: 1716831311226
                      traces: false
                      startTime: 1716795311226
                      entry_time: 1716795311226
                      state: active
                      type: task-history
                      insertTime: 1716795499234
                    - startTime: 1716795211822
                      taskId: 3
                      taskName: auto_on
                      duration: '1440'
                      events:
                      - qos-congestion
                      - sla-violation
                      sites:
                      - '100'
                      - '500'
                      sitesName:
                      - SITE_100
                      - SITE_500
                      stopTime: 1716795289048
                      traces: 'false'
                      state: finished
                      type: task-history
                      tenant: default
                    - startTime: 1716443790022
                      taskId: 1
                      taskName: auto-on
                      duration: '1440'
                      events:
                      - qos-congestion
                      - sla-violation
                      sites:
                      - '100'
                      - '400'
                      - '500'
                      - '600'
                      sitesName:
                      - SITE_100
                      - SITE_400
                      - SITE_500
                      - SITE_600
                      stopTime: 1716530190022
                      traces: 'true'
                      state: finished
                      type: task-history
                      tenant: default
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      x-roles-required: Device Monitoring-read,Device Monitoring-write
  /stream/device/nwpi/tasks/{taskId}/traces:
    get:
      tags:
      - Troubleshooting Tools - Network Wide Path Insight
      description: Get all traces in one task
      operationId: getTaskTrace
      parameters:
      - name: taskId
        in: path
        description: taskId
        required: true
        schema:
          pattern: ^[1-9][0-9]{0,5}$
          type: string
          example: '119'
      - name: taskStartTime
        in: query
        description: task start time
        schema:
          maximum: 10000000000000
          minimum: 1
          type: integer
          format: int64
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        data:
                          type: object
                          properties:
                            devices:
                              type: array
                              items:
                                type: object
                                properties:
                                  app-vis:
                                    type: string
                                  art-vis:
                                    type: string
                                  connectedVManages:
                                    type: string
                                  device-ip:
                                    type: string
                                  device-type:
                                    type: string
                                  dia-vis:
                                    type: string
                                  domain-mon:
                                    type: string
                                  domain_monitor_can_be_started:
                                    type: string
                                  dscp-is-valid:
                                    type: string
                                  duration:
                                    type: string
                                  entry_time:
                                    type: integer
                                    format: int64
                                  expire-time:
                                    type: integer
                                    format: int64
                                  local-system-ip:
                                    type: string
                                  message:
                                    type: string
                                  parent-trace-id:
                                    type: integer
                                    format: int32
                                  qos-mon:
                                    type: string
                                  site-id:
                                    type: string
                                  source-site:
                                    type: string
                                  state:
                                    type: string
                                  trace-id:
                                    type: integer
                                    format: int32
                                  trace-name:
                                    type: string
                                  uuid:
                                    type: string
                                  version:
                                    type: string
                                  vpn-id:
                                    type: string
                                $$ref: '#/components/schemas/NwpiDomainMonitorStateRespPayloadDevicelist'
                            summary:
                              type: object
                              properties:
                                agg-client-prefix:
                                  type: string
                                agg-src-sgt:
                                  type: string
                                agg-svr-prefix:
                                  type: string
                                agg-user-name:
                                  type: string
                                app:
                                  type: string
                                app-grp:
                                  type: string
                                app-vis:
                                  type: string
                                art-vis:
                                  type: string
                                common_app:
                                  type: string
                                device-ip:
                                  type: string
                                devicesCheckInfo:
                                  type: string
                                dia-vis:
                                  type: string
                                domain-mon:
                                  type: string
                                dscp:
                                  type: string
                                dst-ip:
                                  type: string
                                dst-pfx:
                                  type: string
                                dst-pfx-len:
                                  type: string
                                dst-port:
                                  type: string
                                duration:
                                  type: string
                                health-app-server-mem:
                                  type: string
                                health-cpu-core:
                                  type: string
                                health-cpu-load:
                                  type: string
                                health-cpu-load-average:
                                  type: string
                                health-mem-usage:
                                  type: string
                                health-running-traces:
                                  type: integer
                                  format: int32
                                health-server-ip:
                                  type: string
                                hub-wan-vis:
                                  type: string
                                local-drop-rate-threshold:
                                  type: integer
                                  format: int32
                                message:
                                  type: string
                                protocol:
                                  type: string
                                qos-mon:
                                  type: string
                                sampling:
                                  type: string
                                source-site:
                                  type: string
                                source-site-vmanage-version:
                                  type: string
                                spl-intvl:
                                  type: string
                      

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-catalyst-sdwan/refs/heads/main/openapi/cisco-catalyst-sdwan-troubleshooting-tools-network-wide-path-insight-api-openapi.yml