openapi: 3.2.0
info:
title: Assurance Network Device documentation Network Devices API
description: '### OpenAPI specification defined for the purpose of providing visibility into the Network Devices and their health in Catalyst Center
**Relevant Concepts**
| Term | Description |
| -- | -- |
| `Fabric` | A fabric is a logical subdivision of a larger network, containing its own control plane nodes for management, border nodes for routing traffic between sites, and edge nodes that connect devices to the fabric.|'
termsOfService: https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html
contact:
name: Cisco TAC World Wide
url: https://www.cisco.com/c/en/us/support/web/tsd-cisco-worldwide-contacts.html
email: tac@cisco.com
license:
name: Cisco Catalyst Center License
url: https://www.cisco.com/c/en/us/products/collateral/software/dna-software-ebook-cte.html
version: 3.1.5
x-provenance:
method: harvested
authored_by: Cisco Catalyst Center
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: developer.cisco.com
note: 27 Cisco-published OpenAPI 3.0 Assurance documents (185 operations). Ownership confirmed from the tac@cisco.com contact, the Cisco EULA terms-of-service URL and the Cisco Catalyst Center license block carried in each document.
x-evidence:
- type: source
url: https://developer.cisco.com/docs/catalyst-center/
- type: source
url: https://developer.cisco.com/dnacenter/
servers:
- url: https://developer.cisco.com/data/api/v1
tags:
- name: networkDevices
description: Operations related to Catalyst Center - Gets the Network Device details
externalDocs:
description: Catalyst Center Assurance user guide
url: https://www.cisco.com/c/en/us/support/cloud-systems-management/dna-center/products-user-guide-list.html
paths:
/networkDevices:
get:
tags:
- networkDevices
summary: Gets the Network Device details based on the provided query parameters.
description: Gets the Network Device details based on the provided query parameters. When there is no start and end time specified returns the latest device, by default this will use the last 30 minutes of data. details.
operationId: readNetworkDevices
parameters:
- name: startTime
in: query
description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive.
'
schema:
type: integer
format: int64
example: 1705348800000
- name: endTime
in: query
description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive.
'
required: false
schema:
type: integer
format: int64
example: 1705435200000
- name: limit
in: query
description: Maximum number of records to return. In high-scale environments, setting the limit to 500 could lead to increased latency
schema:
maximum: 500
minimum: 1
type: integer
default: 300
- name: offset
in: query
description: Specifies the starting point within all records returned by the API. It's one based offset. The starting value is 1.
schema:
minimum: 1
type: integer
default: 1
- name: sortBy
in: query
description: A field within the response to sort by.
schema:
type: string
- name: order
in: query
description: The sort order of the field ascending or descending.
schema:
type: string
default: asc
enum:
- asc
- desc
- name: siteHierarchy
in: query
description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`)
This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*`
Examples:
`?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested)
`?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: siteHierarchyId
in: query
description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`)
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested)
`?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: siteId
in: query
description: 'The UUID of the site. (Ex. `flooruuid`)
Examples:
`?siteId=id1` (single id requested)
`?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: id
in: query
description: 'The list of entity Uuids. (Ex."6bef213c-19ca-4170-8375-b694e251101c")
Examples: id=6bef213c-19ca-4170-8375-b694e251101c (single entity uuid requested)
id=6bef213c-19ca-4170-8375-b694e251101c&id=32219612-819e-4b5e-a96b-cf22aca13dd9&id=2541e9a7-b80d-4955-8aa2-79b233318ba0 (multiple entity uuid with ''&'' separator)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: managementIpAddress
in: query
description: 'The list of entity management IP Address. It can be either Ipv4 or Ipv6 address or combination of both(Ex. "121.1.1.10")
This field supports wildcard (`*`) character-based search. Ex: `*1.1*` or `1.1*` or `*1.1`
Examples:
managementIpAddresses=121.1.1.10
managementIpAddresses=121.1.1.10&managementIpAddresses=172.20.1.10&managementIpAddresses=200:10&=managementIpAddresses172.20.3.4 (multiple entity IP Address with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
- name: macAddress
in: query
description: "The macAddress of the network device or client\nThis field supports wildcard (`*`) character-based search. \nEx: `*AB:AB:AB*` or `AB:AB:AB*` or `*AB:AB:AB`\nExamples:\n\n`macAddress=AB:AB:AB:CD:CD:CD` (single macAddress requested)\n\n`macAddress=AB:AB:AB:CD:CD:DC&macAddress=AB:AB:AB:CD:CD:FE` (multiple macAddress requested)\n"
style: form
explode: true
schema:
type: array
items:
type: string
- name: family
in: query
description: 'The list of network device family names
Examples:
family=Switches and Hubs (single network device family name )
family=Switches and Hubs&family=Router&family=Wireless Controller (multiple Network device family names with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- Switches and Hubs
- Routers
- Wireless Controller
- Unified AP
- Wireless Sensor
- Third Party Device
- name: type
in: query
description: 'The list of network device type This field supports wildcard (`*`) character-based search. Ex: `*9407R*` or `*9407R` or `9407R*`
Examples:
type=SwitchesCisco Catalyst 9407R Switch (single network device types )
type=Cisco Catalyst 38xx stack-able ethernet switch&type=Cisco 3945 Integrated Services Router G2 (multiple Network device types with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
- name: role
in: query
description: 'The list of network device role.
Examples:
role=CORE, role=CORE&role=ACCESS&role=BORDER ROUTER (multiple Network device serial number with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- ACCESS
- CORE
- DISTRIBUTION
- BORDER ROUTER
- name: maintenanceMode
in: query
description: The device maintenanceMode status true or false
required: false
style: form
explode: true
schema:
type: boolean
- name: softwareVersion
in: query
description: 'The list of network device software version This field supports wildcard (`*`) character-based search. Ex: `*17.8*` or `*17.8` or `17.8*`
Examples:
softwareVersion=2.3.4.0 (single network device software version )
softwareVersion=17.9.3.23&softwareVersion=17.7.1.2&softwareVersion=*.17.7 (multiple Network device software versions with comma separatort)
'
style: form
explode: true
schema:
type: array
items:
type: string
- name: healthScore
in: query
description: 'The list of entity health score categoryies
Examples:
healthScore=good,
healthScore=good&healthScore=fair (multiple entity healthscore values with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- poor
- good
- fair
- noHealth
- name: view
in: query
description: The List of Network Device model views. Please refer to ```NetworkDeviceView``` for the supported list
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: attribute
in: query
description: The List of Network Device model attributes. This is helps to specificy the intrested fields in the request.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: fabricSiteId
in: query
description: 'The fabric site Id or list to fabric site Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?fabricSiteId=fabricSiteUuid)
`?fabricSiteId=fabricSiteUuid1&fabricSiteId=fabricSiteUuid2` (multiple fabricSiteIds requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: l2Vn
in: query
description: 'The L2 Virtual Network Id or list to Virtual Network Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?l2Vn=virtualNetworkId
`?l2Vn=virtualNetworkId1&l2Vn=virtualNetworkId2` (multiple virtualNetworkId''s requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: l3Vn
in: query
description: 'The L3 Virtual Network Id or list to Virtual Network Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?l3Vn=virtualNetworkId
`?l3Vn=virtualNetworkId1&l3Vn=virtualNetworkId2` (multiple virtualNetworkId''s requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: transitNetworkId
in: query
description: 'The Transit Network Id or list to Transit Network Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?transitNetworkId=transitNetworkId
`?transitNetworkId=transitNetworkuuid1&transitNetworkId=transitNetworkuuid1` (multiple transitNetworkIds requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: fabricRole
in: query
description: 'The list of fabric device role.
Examples:
fabricRole=BORDER, fabricRole=BORDER&fabricRole=EDGE (multiple fabric device roles with & separator)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- BORDER
- EDGE
- MAP-SERVER
- LEAF
- SPINE
- TRANSIT-CP
- EXTENDED-NODE
- WLC
- UNIFIED-AP
responses:
'200':
description: Collection of Network Devices Response model on success with aggregate attributes
content:
application/json':
schema:
$ref: '#/components/schemas/NetworkDevicesResponse'
'400':
description: The client made a request that the server could not understand (for example, the request syntax is incorrect).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: The server could not fulfill the request due to internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
1XX:
description: Informational Responses - The server received the request and sent an informational response.
2XX:
description: Successful Responses - The server received the client request, understood it, and accepted it.
3XX:
description: Redirection Messages - The client must take additional action to complete the request.
4XX:
description: Client Error Responses - The client request caused the error.
5XX:
description: Server Error Responses - The server failed to fulfill the request.
default:
description: Unexpected Error
/networkDevices/count:
get:
tags:
- networkDevices
summary: Gets the total Network device counts based on the provided query parameters.
description: Gets the total Network device counts. When there is no start and end time specified returns the latest device total count, by default this will use the last 30 minutes of data.
operationId: readNetworkDevicesCount
parameters:
- name: startTime
in: query
description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive.
'
schema:
type: integer
format: int64
example: 1705348800000
- name: endTime
in: query
description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive.
'
required: false
schema:
type: integer
format: int64
example: 1705435200000
- name: id
in: query
description: 'The list of entity Uuids. (Ex."6bef213c-19ca-4170-8375-b694e251101c")
Examples: id=6bef213c-19ca-4170-8375-b694e251101c (single entity uuid requested)
id=6bef213c-19ca-4170-8375-b694e251101c&id=32219612-819e-4b5e-a96b-cf22aca13dd9&id=2541e9a7-b80d-4955-8aa2-79b233318ba0 (multiple entity uuid with ''&'' separator)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: siteHierarchy
in: query
description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`)
This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*`
Examples:
`?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested)
`?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: siteHierarchyId
in: query
description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`)
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested)
`?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: siteId
in: query
description: 'The UUID of the site. (Ex. `flooruuid`)
Examples:
`?siteId=id1` (single id requested)
`?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: managementIpAddress
in: query
description: 'The list of entity management IP Address. It can be either Ipv4 or Ipv6 address or combination of both(Ex. "121.1.1.10")
This field supports wildcard (`*`) character-based search. Ex: `*1.1*` or `1.1*` or `*1.1`
Examples:
managementIpAddresses=121.1.1.10
managementIpAddresses=121.1.1.10&managementIpAddresses=172.20.1.10&managementIpAddresses=200:10&=managementIpAddresses172.20.3.4 (multiple entity IP Address with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
- name: macAddress
in: query
description: "The macAddress of the network device or client\nThis field supports wildcard (`*`) character-based search. \nEx: `*AB:AB:AB*` or `AB:AB:AB*` or `*AB:AB:AB`\nExamples:\n\n`macAddress=AB:AB:AB:CD:CD:CD` (single macAddress requested)\n\n`macAddress=AB:AB:AB:CD:CD:DC&macAddress=AB:AB:AB:CD:CD:FE` (multiple macAddress requested)\n"
style: form
explode: true
schema:
type: array
items:
type: string
- name: family
in: query
description: 'The list of network device family names
Examples:
family=Switches and Hubs (single network device family name )
family=Switches and Hubs&family=Router&family=Wireless Controller (multiple Network device family names with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- Switches and Hubs
- Routers
- Wireless Controller
- Unified AP
- Wireless Sensor
- Third Party Device
- name: type
in: query
description: 'The list of network device type This field supports wildcard (`*`) character-based search. Ex: `*9407R*` or `*9407R` or `9407R*`
Examples:
type=SwitchesCisco Catalyst 9407R Switch (single network device types )
type=Cisco Catalyst 38xx stack-able ethernet switch&type=Cisco 3945 Integrated Services Router G2 (multiple Network device types with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
- name: role
in: query
description: 'The list of network device role.
Examples:
role=CORE, role=CORE&role=ACCESS&role=BORDER ROUTER (multiple Network device serial number with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- ACCESS
- CORE
- DISTRIBUTION
- BORDER ROUTER
- name: maintenanceMode
in: query
description: The device maintenanceMode status true or false
required: false
style: form
explode: true
schema:
type: boolean
- name: softwareVersion
in: query
description: 'The list of network device software version This field supports wildcard (`*`) character-based search. Ex: `*17.8*` or `*17.8` or `17.8*`
Examples:
softwareVersion=2.3.4.0 (single network device software version )
softwareVersion=17.9.3.23&softwareVersion=17.7.1.2&softwareVersion=*.17.7 (multiple Network device software versions with comma separatort)
'
style: form
explode: true
schema:
type: array
items:
type: string
- name: healthScore
in: query
description: 'The list of entity health score categoryies
Examples:
healthScore=good,
healthScore=good&healthScore=fair (multiple entity healthscore values with & separator)
'
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- poor
- good
- fair
- noHealth
- name: fabricSiteId
in: query
description: 'The fabric site Id or list to fabric site Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?fabricSiteId=fabricSiteUuid)
`?fabricSiteId=fabricSiteUuid1&fabricSiteId=fabricSiteUuid2` (multiple fabricSiteIds requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: l2Vn
in: query
description: 'The L2 Virtual Network Id or list to Virtual Network Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?l2Vn=virtualNetworkId
`?l2Vn=virtualNetworkId1&l2Vn=virtualNetworkId2` (multiple virtualNetworkId''s requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: l3Vn
in: query
description: 'The L3 Virtual Network Id or list to Virtual Network Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?l3Vn=virtualNetworkId
`?l3Vn=virtualNetworkId1&l3Vn=virtualNetworkId2` (multiple virtualNetworkId''s requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: transitNetworkId
in: query
description: 'The Transit Network Id or list to Transit Network Ids to filter the data
This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*`
Examples:
`?transitNetworkId=transitNetworkId
`?transitNetworkId=transitNetworkuuid1&transitNetworkId=transitNetworkuuid1` (multiple transitNetworkIds requested)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: fabricRole
in: query
description: 'The list of fabric device role.
Examples:
fabricRole=BORDER, fabricRole=BORDER&fabricRole=EDGE (multiple fabric device roles with & separator)
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- BORDER
- EDGE
- MAP-SERVER
- LEAF
- SPINE
- TRANSIT-CP
- EXTENDED-NODE
- WLC
- UNIFIED-AP
responses:
'200':
description: Reponse object containing total count of the records after applying requested filters
content:
application/json:
schema:
$ref: '#/components/schemas/CountIntegerResponse'
'400':
description: The client made a request that the server could not understand (for example, the request syntax is incorrect).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: The server could not fulfill the request due to internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
1XX:
description: Informational Responses - The server received the request and sent an informational response.
2XX:
description: Successful Responses - The server received the client request, understood it, and accepted it.
3XX:
description: Redirection Messages - The client must take additional action to complete the request.
4XX:
description: Client Error Responses - The client request caused the error.
5XX:
description: Server Error Responses - The server failed to fulfill the request.
default:
description: Unexpected Error
/networkDevices/{id}:
get:
tags:
- networkDevices
summary: Get the device data for the given device id (Uuid)
description: Returns the device data for the given device Uuid in the specified start and end time range. When there is no start and end time specified returns the latest available data for the given Id, by default this will use the last 30 minutes of data.
operationId: readNetworkDeviceById
parameters:
- name: id
in: path
description: The device Uuid
required: true
style: simple
explode: false
schema:
type: string
format: uuid
- name: startTime
in: query
description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive.
'
schema:
type: integer
format: int64
example: 1705348800000
- name: endTime
in: query
description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive.
'
required: false
schema:
type: integer
format: int64
example: 1705435200000
- name: view
in: query
description: The List of Network Device model views. Please refer to ```NetworkDeviceView``` for the supported list
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: attribute
in: query
description: The List of Network Device model attributes. This is helps to specificy the intrested fields in the request.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: Collection of Network Devices Response model on success with aggregate attributes
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkDeviceResponse'
'400':
description: The client made a request that the server could not understand (for example, the request syntax is incorrect).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: The server could not fulfill the request due to internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
1XX:
description: Informational Responses - The server received the request and sent an informational response.
2XX:
description: Successful Responses - The server received the client request, understood it, and accepted it.
3XX:
description: Redirection Messages - The client must take additional action to complete the request.
4XX:
description: Client Error Responses - The client request caused the error.
5XX:
description: Server Error Responses - The server failed to fulfill the request.
default:
description: Unexpected Error
/networkDevices/{id}/trendAnalytics:
post:
tags:
- networkDevices
summary: The Trend analytcis data for the network Device in the specified time range
description: "The Trend analytcis data for the network Device in the specified time range. The data is grouped based on the trend time Interval, other input parameters like attributes and aggregate attributes. The default time interval range is 3 hours when start and endTime is not provided.\n\n**How the filtering behavior works**\n\nThe filters field in each post body can be used in numerous ways:\n\nEach filter in the list of filters will applied ''together''\n\nIn the example below, this would request filtering the cpu data by the ``switch 1`` cpu indexes.\n\n```\n\"filters\": [\n {\n \"key\": \"cpuName\",\n \"operator\": \"like\",\n \"value\": \"Switch 1\"\n }\n]\n"
operationId: readDeviceTrendAnalytics
parameters:
- name: id
in: path
description: The device Uuid
required: true
style: simple
explode: false
schema:
type: string
format: uuid
requestBody:
description: Payload to query trend data for a Network Device
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkDeviceTrendRe
# --- truncated at 32 KB (179 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-catalyst-center/refs/heads/main/openapi/cisco-catalyst-center-networkdevices-api-openapi.yml