Catalyst Center

Catalyst Center intent-based APIs, SD-Access fabric, and network assurance workflows.

API Authentication

Catalyst Center (formerly DNA Center) uses token-based auth. All API calls require a bearer token.

Get authentication token

DNAC_HOST="catalyst-center.example.com"
TOKEN=$(curl -s -k -X POST \
  "https://${DNAC_HOST}/dna/system/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -u "admin:password" | jq -r '.Token')
echo "${TOKEN}"

Output

{"Token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}

Token is valid for 1 hour. The endpoint path /dna/system/api/v1/auth/token is the same as the legacy DNA Center path — Cisco kept backward compatibility.

Device Inventory

List all network devices

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/network-device" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response[] | {hostname, managementIpAddress, platformId, softwareVersion, role}'

Output

{
  "hostname": "core-sw-01",
  "managementIpAddress": "10.50.1.10",
  "platformId": "C9300-48T",
  "softwareVersion": "17.9.4",
  "role": "ACCESS"
}

Get device count

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/network-device/count" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response'

Get specific device by ID

DEVICE_ID="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/network-device/${DEVICE_ID}" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response | {hostname, serialNumber, upTime, lastUpdateTime}'

Filter devices by platform

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/network-device?platformId=C9300-48T" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response[] | .hostname'

Site Topology

Get site hierarchy

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/site" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response[] | {siteNameHierarchy, id, additionalInfo}'

Output

{
  "siteNameHierarchy": "Global/US/Los Angeles/Building-A/Floor-1",
  "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "additionalInfo": [...]
}

Get physical topology — network graph of device connections

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/topology/physical-topology" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response | {nodes: [.nodes[] | {label, role, ip}], links: (.links | length)}'

Command Runner — Execute CLI on Devices via API

Run show commands on one or more devices

curl -s -k -X POST \
  "https://${DNAC_HOST}/dna/intent/api/v1/network-device-poller/cli/read-request" \
  -H "X-Auth-Token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": ["show version", "show ip interface brief"],
    "deviceUuids": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"]
  }' | jq '.response'

Output — returns a task ID (async operation)

{"taskId": "cccccccc-cccc-cccc-cccc-cccccccccccc", "url": "/api/v1/task/cccccccc-cccc-cccc-cccc-cccccccccccc"}

Poll task for completion and get results

TASK_ID="cccccccc-cccc-cccc-cccc-cccccccccccc"
# Wait for task completion
curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/task/${TASK_ID}" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response | {isError, progress}'

# Get file ID from completed task, then download output
FILE_ID=$(curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/task/${TASK_ID}" \
  -H "X-Auth-Token: ${TOKEN}" | jq -r '.response.progress' | jq -r '.fileId')

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/file/${FILE_ID}" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.[].commandResponses.SUCCESS'

Command Runner is asynchronous. POST returns a task ID; you must poll the task endpoint until isError is false and progress contains the file ID. Plan for 5-15 second wait.

Template Deployment

List available templates

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/template-programmer/template" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.[] | {name, projectName, templateId}'

Deploy a template to a device — push configuration

curl -s -k -X POST \
  "https://${DNAC_HOST}/dna/intent/api/v1/template-programmer/template/deploy" \
  -H "X-Auth-Token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
    "targetInfo": [{
      "id": "10.50.1.10",
      "type": "MANAGED_DEVICE_IP",
      "params": {
        "vlan_id": "100",
        "vlan_name": "USERS"
      }
    }]
  }' | jq

SDA — Software-Defined Access

Get fabric domains

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/business/sda/fabric" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.[] | {fabricName, fabricDomainType}'

Get virtual networks (VNs)

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/business/sda/virtual-network" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.[] | {virtualNetworkName, isGuestVirtualNetwork}'

SDA concepts mapped to traditional networking:

SDA Term              Traditional Equivalent
─────────────────────────────────────────────
Fabric               Overlay network (VXLAN)
Control Plane Node   LISP Map-Server/Resolver
Edge Node            Access switch
Border Node          Distribution/core gateway
Virtual Network      VRF
Host Pool            VLAN/subnet
Scalable Group       SGACL / TrustSec group
Transit              Inter-fabric routing

Assurance — Network Health

Get overall network health

EPOCH_MS=$(date +%s%3N)
curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/client-health?timestamp=${EPOCH_MS}" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response[] | {scoreCategory: .scoreDetail[].scoreCategory.value, clientCount: .scoreDetail[].clientCount}'

Get device health summary

curl -s -k \
  "https://${DNAC_HOST}/dna/intent/api/v1/network-health?timestamp=${EPOCH_MS}" \
  -H "X-Auth-Token: ${TOKEN}" | jq '.response[] | {category: .healthDistir498Score[].category, count}'

Assurance APIs require epoch timestamp in milliseconds. date +%s%3N provides this on Linux. On macOS, use $$(date +%s) * 1000.