Skip to content
Log in Sign up My account

6.4 Catalyst Center and SD-WAN Manager APIs

Blueprint 6.4: Describe APIs for Cisco Catalyst Center and SD-WAN Manager

  • Catalyst Center: Intent API (northbound), Integration API (westbound), Multivendor SDK (southbound), Events and Notifications (eastbound); token authentication; synchronous and task-based calls
  • SD-WAN Manager (formerly vManage): the /dataservice REST API, session-cookie and XSRF-token authentication, and the main API categories
  • Reading a short script that calls either controller

The verb is describe. Know what each API family is for, how a script authenticates, what the URL and response look like, and how asynchronous work is tracked. Interpreting the status codes and payloads in detail is objective 6.5.

Why controller APIs

Device-level APIs (NETCONF, RESTCONF) talk to one box at a time. A controller already knows the whole network: inventory, topology, health, policy and templates. Its northbound API lets a script ask network-wide questions ("which devices run an old image?") or make network-wide changes ("deploy this template to every branch") in one call, and the controller handles the per-device work.

graph TB
  APP["Scripts, ITSM, dashboards"] -->|"Northbound REST API"| CTRL["Controller<br/>Catalyst Center or SD-WAN Manager"]
  CTRL -->|"Southbound: SSH, NETCONF, SNMP, HTTPS"| D1["Router"]
  CTRL -->|"Southbound"| D2["Switch"]
  CTRL -->|"Southbound"| D3["WAN Edge"]

Northbound means from the controller up to applications. Southbound means from the controller down to devices. Catalyst Center also names eastbound (events going out) and westbound (integration with other IT systems).

Catalyst Center APIs

Catalyst Center was formerly called Cisco DNA Center, and the API paths still begin with /dna/.

Direction Name Purpose Examples
Northbound Intent API REST API to read and change the network as a whole Device inventory, site health, client health, templates, command runner, path trace
Westbound Integration API Connect Catalyst Center to other IT systems ITSM such as ServiceNow, IP address management (IPAM), reporting
Southbound Multivendor SDK Device packages that let Catalyst Center manage third-party devices Support for non-Cisco switches
Eastbound Events and Notifications Push events from Catalyst Center to other systems Webhooks, email, syslog and SNMP trap destinations for assurance issues 
graph LR
  ITSM["ITSM, IPAM"] <-->|"Westbound<br/>Integration API"| CC["Catalyst Center"]
  APP["Scripts and apps"] <-->|"Northbound<br/>Intent API, REST"| CC
  CC -->|"Eastbound<br/>events, webhooks"| EV["Event receivers"]
  CC -->|"Southbound<br/>Multivendor SDK"| DEV["Cisco and third-party devices"]

Intent API groups

The Intent API documentation (in the GUI under Platform, Developer Toolkit, and on Cisco DevNet) groups calls into domains:

Domain What it covers
Authentication Getting a token
Know Your Network Sites, topology, devices, clients, users, issues and health
Site Management Site design, network settings, software image management (SWIM), Plug and Play onboarding, configuration templates
Connectivity SD-Access fabric and wireless
Operational Tasks Command runner, discovery, path trace, file, task and tag
Policy Application policy
Event Management Event subscriptions and notifications

Authentication

Catalyst Center uses token-based authentication.

  1. The client sends POST /dna/system/api/v1/auth/token with HTTP Basic authentication (the username and password, Base64-encoded in the Authorization header).
  2. Catalyst Center returns a JSON body containing a token: {"Token": "eyJhbGciOi..."}.
  3. Every later request carries the token in the X-Auth-Token header.
  4. The token expires after a fixed lifetime (60 minutes by default). After that the API returns 401 and the script must request a new one.
sequenceDiagram
  participant S as Script
  participant C as Catalyst Center
  S->>C: POST /dna/system/api/v1/auth/token (Basic auth)
  C-->>S: 200 OK, Token
  S->>C: GET /dna/intent/api/v1/network-device (X-Auth-Token)
  C-->>S: 200 OK, response list
  S->>C: POST /dna/intent/api/v1/network-device-poller/cli/read-request
  C-->>S: 202 Accepted, taskId
  S->>C: GET /dna/intent/api/v1/task/taskId
  C-->>S: 200 OK, progress and isError

URL and response shape

https://catc.example.com/dna/intent/api/v1/network-device?platformId=C9300-48U breaks down as:

Part Value
Scheme and host https://catc.example.com
API family and version /dna/intent/api/v1
Resource /network-device
Query parameter (filter) ?platformId=C9300-48U

Intent API responses wrap the data in a response key, usually next to a version key:

{
  "response": [
    {
      "hostname": "edge-sw1.example.com",
      "managementIpAddress": "10.10.20.81",
      "platformId": "C9300-48U",
      "softwareVersion": "17.12.4",
      "reachabilityStatus": "Reachable",
      "role": "ACCESS",
      "serialNumber": "FOC1234X0AB",
      "id": "6a49c827-9b28-490b-8df0-8b6c3b582d8c"
    }
  ],
  "version": "1.0"
}

response is a list when the call returns a collection and a single object or value when it returns one item. For example, GET /dna/intent/api/v1/network-device/count returns {"response": 12, "version": "1.0"}. The id is the device UUID that other calls use to refer to the device.

Synchronous and asynchronous calls

Reads (GET) normally return the data straight away with 200 OK. Many calls that change something, or that take time (command runner, template deployment, discovery), are asynchronous: Catalyst Center returns 202 Accepted with a task ID, and the work continues in the background.

{
  "response": {
    "taskId": "a7c2f1e4-55b0-4c3e-9d21-0f6a3b8e1c90",
    "url": "/api/v1/task/a7c2f1e4-55b0-4c3e-9d21-0f6a3b8e1c90"
  },
  "version": "1.0"
}

The script then polls GET /dna/intent/api/v1/task/{taskId} and reads fields such as isError, progress, failureReason and endTime. A task that finished with "isError": true was accepted by the API but failed on the network.

Exam trap

A 202 is not success. It means "accepted, not yet done". Only the task result tells you whether the change worked. If a question shows a 202 and a taskId, the correct next step is to query the task API, not to repeat the request or assume it succeeded.

A Catalyst Center script

import requests
from requests.auth import HTTPBasicAuth

CATC = "https://catc.example.com"


def get_token(user, password):
    resp = requests.post(
        f"{CATC}/dna/system/api/v1/auth/token",
        auth=HTTPBasicAuth(user, password),
        verify=False,
        timeout=15,
    )
    resp.raise_for_status()
    return resp.json()["Token"]


def unreachable_devices(token):
    headers = {"X-Auth-Token": token, "Accept": "application/json"}
    resp = requests.get(
        f"{CATC}/dna/intent/api/v1/network-device",
        headers=headers,
        verify=False,
        timeout=15,
    )
    resp.raise_for_status()
    return [
        (d["hostname"], d["managementIpAddress"])
        for d in resp.json()["response"]
        if d["reachabilityStatus"] != "Reachable"
    ]


if __name__ == "__main__":
    tok = get_token("devnetuser", "example-password")
    for name, ip in unreachable_devices(tok):
        print(f"{name} ({ip}) is not reachable")

What to notice: the token comes from the Token key of the auth response; it is sent in X-Auth-Token, not in Authorization; the device list is under response; and the list comprehension keeps only devices whose reachabilityStatus is not Reachable.

Cisco also publishes a Python SDK for Catalyst Center (dnacentersdk on PyPI) and Ansible collections that wrap the same REST calls, so you do not have to handle tokens and task polling yourself.

SD-WAN Manager APIs

SD-WAN Manager (formerly vManage) exposes a REST API under /dataservice. Its interactive documentation (Swagger) is served by the Manager itself at https://<manager>/apidocs.

Authentication

SD-WAN Manager uses a session cookie plus, for changes, an XSRF token.

  1. POST /j_security_check with form-encoded fields j_username and j_password. On success the Manager sets a JSESSIONID cookie.
  2. GET /dataservice/client/token (with the cookie) returns a token as plain text.
  3. Later requests send the cookie, and requests that change state (POST, PUT, DELETE) also send the header X-XSRF-TOKEN: <token>.
  4. GET /logout ends the session.
sequenceDiagram
  participant S as Script
  participant M as SD-WAN Manager
  S->>M: POST /j_security_check (form: j_username, j_password)
  M-->>S: 200, Set-Cookie JSESSIONID
  S->>M: GET /dataservice/client/token (cookie)
  M-->>S: 200, token text
  S->>M: GET /dataservice/device (cookie)
  M-->>S: 200, header and data
  S->>M: POST /dataservice/... (cookie and X-XSRF-TOKEN)
  M-->>S: 200, id of the action

Exam trap

Do not mix up the two controllers. Catalyst Center: Basic auth to /dna/system/api/v1/auth/token, token in X-Auth-Token. SD-WAN Manager: form login to /j_security_check, JSESSIONID cookie, and X-XSRF-TOKEN for changes. A question that shows j_username is about SD-WAN Manager.

API categories and common calls

Category Purpose Example
Device Inventory WAN Edges and controllers known to the overlay GET /dataservice/system/device/vedges
Monitoring Status from the Manager's database: devices, alarms, events, statistics GET /dataservice/device, GET /dataservice/alarms
Real-Time Monitoring Live data fetched from a device on demand GET /dataservice/device/bfd/sessions?deviceId=10.1.1.1
Configuration Templates, configuration groups, policies GET /dataservice/template/device
Troubleshooting Tools Ping, traceroute, packet capture from the Manager Device action endpoints
Certificate Management Device certificates and the authorised list Certificate endpoints
Administration Users, groups, settings GET /dataservice/admin/user

Real-time monitoring calls make the Manager query the device live, so they are slower and heavier than monitoring calls that read the Manager's own database. Use them for one device at a time. The deviceId in these calls is the device's system IP.

Response shape

SD-WAN Manager responses usually have a header object (column definitions and metadata for the GUI tables) and a data list with the records:

{
  "header": {
    "generatedOn": 1791360000000,
    "title": "Devices"
  },
  "data": [
    {
      "deviceId": "10.1.1.1",
      "system-ip": "10.1.1.1",
      "host-name": "br1-edge1",
      "device-type": "vedge",
      "site-id": "100",
      "reachability": "reachable",
      "version": "17.12.4"
    },
    {
      "deviceId": "10.0.0.11",
      "system-ip": "10.0.0.11",
      "host-name": "controller-1",
      "device-type": "vsmart",
      "site-id": "1",
      "reachability": "reachable",
      "version": "20.12.4"
    }
  ]
}

The header content above is trimmed. Field names in SD-WAN Manager responses often use hyphens (host-name, system-ip), and device-type still uses the original product names: vedge for any WAN Edge (including IOS XE routers), vsmart for Controllers, vbond for Validators and vmanage for Managers.

Long-running configuration actions, such as attaching a device template, return an action id. The script polls GET /dataservice/device/action/status/{id} until the action completes, the same pattern as the Catalyst Center task API.

An SD-WAN Manager script

import requests

MGR = "https://sdwan-mgr.example.com"


def login(user, password):
    s = requests.Session()
    s.verify = False
    r = s.post(f"{MGR}/j_security_check",
               data={"j_username": user, "j_password": password},
               timeout=15)
    # A failed login returns an HTML login page instead of an empty body
    if r.status_code != 200 or "<html" in r.text.lower():
        raise RuntimeError("login failed")
    token = s.get(f"{MGR}/dataservice/client/token", timeout=15).text
    s.headers.update({"X-XSRF-TOKEN": token})
    return s


def edges_down(session):
    r = session.get(f"{MGR}/dataservice/device", timeout=15)
    r.raise_for_status()
    return [d["host-name"] for d in r.json()["data"]
            if d["device-type"] == "vedge" and d["reachability"] != "reachable"]


if __name__ == "__main__":
    sess = login("admin", "example-password")
    print("Unreachable edges:", edges_down(sess))
    sess.get(f"{MGR}/logout", timeout=15)

The requests.Session() object stores the JSESSIONID cookie from the login and sends it automatically, and its headers dictionary adds the XSRF token to every later request. The login check looks for an HTML page because SD-WAN Manager answers a bad password with its login page rather than an error code; this is a well-known quirk, so test it in your own lab before relying on it.

Comparing the two

Catalyst Center SD-WAN Manager
Former name DNA Center vManage
Base path /dna/intent/api/v1/... /dataservice/...
Login POST /dna/system/api/v1/auth/token, Basic auth POST /j_security_check, form fields
Credential on later calls X-Auth-Token header JSESSIONID cookie, plus X-XSRF-TOKEN for changes
Data key in responses response data
Long-running work 202 with taskId, poll /task/{taskId} Action id, poll /device/action/status/{id}
API documentation GUI Developer Toolkit, Cisco DevNet https://<manager>/apidocs, Cisco DevNet
Domain Campus and branch LAN, SD-Access, assurance WAN overlay: edges, controllers, policies, templates

Lab: call both controller APIs

No Catalyst Center or SD-WAN Manager fits on a laptop. Use the free always-on Catalyst Center and SD-WAN sandboxes from the DevNet Sandbox catalog on developer.cisco.com. The current hostnames and read-only credentials are listed on each sandbox page; they change from time to time, so do not copy them from old blog posts.

Topology: AUTO (any Ubuntu host or your laptop with Python 3 and requests) with internet access to the sandbox.

graph LR
  AUTO["AUTO<br/>Python 3, requests"] -->|"HTTPS 443"| CC["Catalyst Center sandbox"]
  AUTO -->|"HTTPS 443"| SM["SD-WAN Manager sandbox"]

  1. Get a Catalyst Center token with curl and confirm you see the Token key:

    curl -sk -X POST -u <user>:<password> https://<catc-sandbox>/dna/system/api/v1/auth/token
{"Token":"eyJ0eXAiOiJKV1Qi..."}

  2. Use the token to count devices:

    curl -sk -H "X-Auth-Token: <token>" https://<catc-sandbox>/dna/intent/api/v1/network-device/count
{"response":14,"version":"1.0"}

    The number depends on the sandbox.

  3. Repeat step 2 with a deliberately wrong token. Expect 401.

  4. Save the Catalyst Center script above as catc.py, put in the sandbox host and credentials, and run it. Then change it to print every device's hostname, platformId and softwareVersion.

  5. Log in to the SD-WAN sandbox with curl, storing the cookie, and list devices:

    curl -sk -c cj.txt -X POST -d "j_username=<user>&j_password=<password>" \
  https://<sdwan-sandbox>/j_security_check
curl -sk -b cj.txt https://<sdwan-sandbox>/dataservice/device

    The second command returns the header and data structure shown above, one entry per controller and edge.

  6. Run the SD-WAN Manager script against the sandbox. Then add a call to /dataservice/device/control/connections?deviceId=<system-ip of one edge> and print each control connection's peer type and state.

  7. Open https://<sdwan-sandbox>/apidocs in a browser while logged in and find the category that contains /device/bfd/sessions.

Quick check

Which header carries the credential on a Catalyst Center Intent API call after login?

X-Auth-Token, containing the token returned by POST /dna/system/api/v1/auth/token.

Which Catalyst Center API direction would a ServiceNow integration use?

Westbound, the Integration API. Northbound is the Intent API used by scripts and apps; eastbound is events and notifications; southbound is device management, including the Multivendor SDK.

An SD-WAN Manager GET works, but a POST from the same script returns 403. The session cookie is valid. What is the most likely cause?

The script did not send the X-XSRF-TOKEN header obtained from /dataservice/client/token. State-changing requests need it.

References

  • Cisco DevNet: Catalyst Center (DNA Center) API documentation and SD-WAN API documentation, plus the always-on sandboxes
  • Cisco Catalyst Center Platform User Guide, chapter on the Developer Toolkit and APIs (search on cisco.com)
  • Cisco Catalyst SD-WAN Monitor and Maintain guide and SD-WAN Manager API reference (search on cisco.com)
  • Cisco Live On-Demand Library: search "Catalyst Center API" and "SD-WAN API"