Cisco Catalyst SD-WAN Manager API

A working reference for every API area: what each endpoint family does, how the Manager serves the call, how to implement it, and where the data actually comes from.

Sources: DevNet API guide Release 26.1 (spec 26.1.0, 2026-01-06) and Release 20.18; Cisco Catalyst SD-WAN Getting Started Guide (updated July 2026); Cisco Control Components guide 26.x. Acronyms are spelled out on first use.

The Manager API is a REST (Representational State Transfer) interface for controlling, configuring, and monitoring devices in an overlay. Cisco frames four use cases: provisioning, network visibility, third-party tool integration, and Network as Code. Every path is prefixed with /dataservice, payloads are JSON except a few file uploads, and the calling role needs API access permission.

Where a call stops decides everything

The Manager sits between your tool and the routers and keeps three stores. A call either reads one of those stores or opens a live NETCONF (Network Configuration Protocol) session to the router. Cost, freshness, and pagination all follow from which one you hit.

Authentication and sessions

Three methods are supported. API keys and JWT (JSON Web Token) arrived in 20.18; session cookies remain for backward compatibility. All three require the XSRF (cross-site request forgery) token on every non-GET request.

Implementation

# Python — minimal JWT client with refresh and XSRF handling
import requests, time

class Manager:
    def __init__(self, host, user, pw, duration=1800, verify=True):
        self.base = f"https://{host}"; self.s = requests.Session(); self.s.verify = verify
        self.user, self.pw, self.duration = user, pw, duration
        self.login()

    def login(self):
        r = self.s.post(f"{self.base}/jwt/login",
                        json={"username": self.user, "password": self.pw, "duration": self.duration})
        r.raise_for_status(); body = r.json()
        self.token, self.csrf = body["token"], body.get("csrf")
        self.exp = time.time() + self.duration - 60
        self.s.headers.update({"Authorization": f"Bearer {self.token}",
                               "X-XSRF-TOKEN": self.csrf, "Content-Type": "application/json"})

    def refresh(self):
        r = self.s.post(f"{self.base}/jwt/refresh"); r.raise_for_status()
        self.token = r.json()["token"]; self.exp = time.time() + self.duration - 60
        self.s.headers["Authorization"] = f"Bearer {self.token}"

    def call(self, method, path, **kw):
        if time.time() > self.exp: self.refresh()
        r = self.s.request(method, f"{self.base}/dataservice{path}", **kw)
        if r.status_code == 401: self.login(); r = self.s.request(method, f"{self.base}/dataservice{path}", **kw)
        r.raise_for_status(); return r.json()

Pagination, rate limits, and async tasks

Pagination follows the data source

Sorting and filtering are only available for device state and statistics APIs; the allowed field names for a table come from its /fields endpoint.

Rate limits

The per-node bulk limit is tunable with request nms server-proxy set ratelimit followed by request nms server-proxy restart on every node. Exhausting a limit returns 429 with no Retry-After header, so back off on your own schedule.

Every write is a task

Configuration pushes and device actions return a task ID, not a result. Poll GET /device/action/status/{taskId} and read the activity array until statusId settles.

def wait_task(m, task_id, timeout=900):
    t0 = time.time()
    while time.time() - t0 < timeout:
        st = m.call("GET", f"/device/action/status/{task_id}")
        if st["summary"]["status"] == "done":
            return [(d["deviceIP"], d["statusId"]) for d in st["data"]]
        time.sleep(8)
    raise TimeoutError(task_id)

RBAC (role-based access control)

Each operation in the OpenAPI spec carries an x-roles-required value such as Template Deploy-write or Config Group > Device > Deploy-write. Build service accounts from those values: a read-only monitoring group for collectors, and a separate Settings-write account only for webhook rule management.

Administration and settings Configuration DB

Global Manager parameters, user and group management, tenants, software maintenance, and backup. Everything here reads and writes the configuration database; nothing touches a device except software install and reboot actions.

How a user is created

1. GET /admin/usergroup to confirm the group exists, or POST /admin/usergroup with the feature list.
2. POST /admin/user with userName, password, group[], optional resGroupName.
3. Verify with GET /admin/user; the password is never returned.

m.call("POST", "/admin/usergroup", json={
  "groupName": "monitoring-ro",
  "tasks": [{"feature": "Device Monitoring", "enabled": True, "read": True, "write": False},
            {"feature": "Alarms",            "enabled": True, "read": True, "write": False},
            {"feature": "Device Inventory",  "enabled": True, "read": True, "write": False}]})
m.call("POST", "/admin/user", json={"userName": "svc-collector", "password": "…", "group": ["monitoring-ro"]})

Device inventory Configuration DB

The foundation for everything else: which devices exist, whether they are reachable, and what state their certificates and control connections are in. All served from the Manager's own database.

devices = m.call("GET", "/device")["data"]
down = [d for d in devices if d.get("reachability") != "reachable"]
print(f"{len(devices)} devices, {len(down)} unreachable")

UX 1.0 — templates and centralized policy Writes config

UX (user experience) 1.0 is the template era: feature templates compose into device templates, which are attached to devices with per-device variables. Centralized policy is assembled and activated on the Controller. Still the majority of brownfield estates.

tpl = "a1b2…"; dev = "C8K-…uuid"
sheet = m.call("POST", "/template/device/config/input",
               json={"templateId": tpl, "deviceIds": [dev], "isEdited": False, "isMasterEdited": False})
row = sheet["data"][0]
row.update({"//system/host-name": "BR-100-R1", "//system/system-ip": "10.255.1.1", "//system/site-id": "100"})
task = m.call("POST", "/template/device/config/attachfeature",
              json={"deviceTemplateList": [{"templateId": tpl, "device": [row], "isEdited": False, "isMasterEdited": False}]})
print(wait_task(m, task["id"]))

UX 2.0 — configuration groups and feature profiles Writes config

The strategic direction for new deployments. A configuration group is a bundle of feature profiles (system, transport, service, policy-object, CLI, other); devices are associated to the group, receive per-device variables, and are deployed in one task. Policy groups and topology groups follow the same CRUD (create, read, update, delete) + associate + deploy pattern.

gid = m.call("POST", "/v1/config-group", json={"name": "branch-std", "solution": "sdwan", "description": "Standard branch",
              "profiles": [{"id": SYSTEM_PROFILE}, {"id": TRANSPORT_PROFILE}, {"id": SERVICE_PROFILE}]})["id"]
m.call("PUT", f"/v1/config-group/{gid}/device/associate", json={"devices": [{"id": dev}]})
m.call("PUT", f"/v1/config-group/{gid}/device/variables",
       json={"solution": "sdwan", "devices": [{"device-id": dev,
             "variables": [{"name": "host_name", "value": "BR-100-R1"}, {"name": "system_ip", "value": "10.255.1.1"}, {"name": "site_id", "value": 100}]}]})
task = m.call("POST", f"/v1/config-group/{gid}/device/deploy", json={"devices": [{"id": dev}]})
wait_task(m, task["parentTaskId"])

SD-WAN services and partner integrations Writes config

Customer questions → endpoints Statistics DB

NOCs (network operations centres) don't ask for endpoint families; they ask "is site 90 healthy?" This table maps the common questions to the scalable endpoint and to the troubleshooting-only equivalent. Every scalable row is served from the Manager; none touches a device.

Tunnel is not circuit

Customers use the words interchangeably; the API doesn't. A tunnel (path) is one local device + colour to one remote device + colour. A circuit (transport) is one local device + colour, carrying many tunnels. Group your aggregation accordingly, and never group by local_color alone across devices — it merges every "mpls" in the fabric into one row.

The same device has four names

Inventory uses hyphenated fields, statistics use underscores, and real-time calls use deviceId. Mixing them up is the number one cause of "the API returns nothing" tickets.

Device state — bulk State cache

The "what is up or down right now" view. The Manager's collection manager polls devices on its own schedule and stores current state; you read the cache, and the router is never touched. One request returns the whole fabric in batches.

def state(m, table, count=1000):
    rows, start = [], None
    while True:
        q = f"count={count}" + (f"&startId={start}" if start else "")
        r = m.call("GET", f"/data/device/state/{table}?{q}")
        rows += r["data"]; pi = r.get("pageInfo", {})
        if not pi.get("moreEntries"): return rows
        start = pi["endId"]

bfd = state(m, "BFDSessions")
down = [s for s in bfd if s.get("state") != "up"]

Statistics — export and query Statistics DB

Devices export counters to the Manager, which stores them in a time-series database. Two flavours share the same store: a bulk export for moving raw rows out, and a query/aggregation API that does the maths server-side and powers the Manager GUI charts.

Bulk export

Discover fields before you filter

Every statistics table exposes GET /statistics/{table}/fields (fields you can return) and GET /statistics/{table}/query/fields (fields you can filter on). Field names differ between releases; hard-coding them without checking is how integrations break silently on upgrade.

fields = {f["property"] for f in m.call("GET", "/statistics/approute/fields")}
assert {"latency","jitter","loss_percentage","local_color"} <= fields

Query and aggregation

# Bulk export of tunnel SLA rows for the last hour
from datetime import datetime, timedelta
end = datetime.utcnow(); start = end - timedelta(hours=1)
fmt = lambda t: t.strftime("%Y-%m-%dT%H:%M:%S")
path = f"/data/device/statistics/approutestatsstatistics?startDate={fmt(start)}&endDate={fmt(end)}&count=10000&timeZone=UTC"
rows, r = [], m.call("GET", path)
while True:
    rows += r["data"]
    if not r.get("hasMoreData"): break
    r = m.call("GET", f"/data/device/statistics/approutestatsstatistics?scrollId={r['scrollId']}&count=10000")

# Server-side aggregation: hourly mean latency per tunnel, last 24 h
q = {"query": {"condition": "AND", "rules": [
        {"field": "entry_time", "type": "date", "value": ["24"], "operator": "last_n_hours"},
        {"field": "vdevice_name", "type": "string", "value": ["10.255.1.1"], "operator": "in"}]},
     "aggregation": {"field": [{"property": "name", "sequence": 1}],
                     "histogram": {"property": "entry_time", "type": "hour", "interval": 1, "order": "asc"},
                     "metrics": [{"property": "latency", "type": "avg"}, {"property": "loss_percentage", "type": "avg"}]}}
agg = m.call("POST", "/statistics/approute/aggregation", json=q)["data"]

Alarms, events, and webhooks Alarm store

Alarms are correlated conditions with severity; events are the raw notifications behind them. Retrieving alarms over REST means frequent polling, so the Manager can push them instead: a notification rule with a webhook URL delivers an HTTP POST the moment a matching alarm is raised.

m.call("POST", "/notifications/rule", json={
  "notificationRuleName": "noc-critical-major",
  "severity": ["Critical", "Major"],
  "alarmName": [],                      # empty = all alarm types
  "devicesAttached": [],                # empty = all devices; or [{"system-ip": "…"}]
  "webHookEnabled": True, "webhookUrl": "https://hooks.example.com/sdwan",
  "webhookUsername": "svc", "webhookPassword": "…",
  "emailEnabled": False})

# Backfill: critical alarms in the last 24 h for one site
q = {"query": {"condition": "AND", "rules": [
      {"field": "entry_time", "type": "date", "value": ["24"], "operator": "last_n_hours"},
      {"field": "severity", "type": "string", "value": ["Critical"], "operator": "in"}]}, "size": 1000}
alarms = m.call("POST", "/alarms?site-id=100", json=q)["data"]

Real-time monitoring Reaches the device

Real-time monitoring APIs query device state and information in real time. The Manager opens a NETCONF session to the router over its DTLS (Datagram Transport Layer Security) control connection, runs the query, and returns the result — one device per call. This is the only monitoring path that consumes CPU on the router, and it shares the control channel with configuration pushes and OMP (Overlay Management Protocol) updates.

The synced twins

Many real-time endpoints have a synced variant that returns the same shape from the Manager NMS cache: /device/system/status vs /device/system/synced/status, /device/bfd/sessions vs /device/bfd/synced/sessions, /device/control/connections vs /device/control/synced/connections, /hardware/alarms vs /hardware/synced/alarms. If you need one device's view without touching it, use the synced twin.

Endpoint catalog (26.1)

All are GET /dataservice/…?deviceId=<system-ip>. Cisco annotates most as "on vEdge routers only"; the same paths generally work on Catalyst IOS XE edges, but test each one — bridge, PPP, and dot1x are Viptela-OS specific.

Sanctioned implementation: an on-demand runbook

# Triggered by an engineer for ONE device. Never scheduled.
def site_snapshot(m, system_ip):
    q = f"?deviceId={system_ip}"
    return {
      "control": m.call("GET", "/device/control/connections" + q)["data"],
      "bfd":     m.call("GET", "/device/bfd/sessions" + q)["data"],
      "sla":     m.call("GET", "/device/app-route/statistics" + q)["data"],
      "ifaces":  m.call("GET", "/device/interface/error_stats" + q)["data"],
      "cpu":     m.call("GET", "/device/system/status" + q)["data"],
    }

Troubleshooting tools Reaches the device

Diagnostic operations that go beyond a single query: log bundles, path traces, utilities. Tagged in the spec as Troubleshooting Tools - Device Connectivity and Troubleshooting Tools - Network Wide Path Insight.

Errors and resilience

HTTP status codes

When the API returns 200 and nothing

An empty data array with HTTP 200 is not an error to the Manager. Work it top-down:

Failure patterns and fixes

What changed from 20.18 to 26.1

The Monitoring and Troubleshooting changelog ends with an explicit statement that result-API changes broke backward compatibility. Integrations built against 20.x should be reviewed before an upgrade.

Guidance checklist

1. Never schedule real-time calls. Per-device NETCONF pulls over the control plane belong in an on-demand runbook, scoped to one device or site.
2. Poll bulk state for "now." One call per table returns the whole fabric. Five-minute cadence covers NOC dashboards; use /health/devices/overview for the headline.
3. Export statistics in windows. Bulk /data/device/statistics/{table} with scrollId paging, two concurrent, 48/min per node; use /statistics/{table}/aggregation when the Manager can do the maths.
4. Push alarms, don't pull them. Register /notifications/rule webhooks; use /alarms only for backfill.
5. Build a resilient client. Short-lived JWT with refresh; XSRF on every non-GET; backoff on 429 (no Retry-After); re-auth once on 401; inspect the login body.
6. Ramp load gradually and watch the Manager. Start with a low request count and interval, increase one dimension at a time, and watch every Manager node for CPU and memory, API latency and timeouts, 429 and 5xx rates, statistics-query and bulk-export duration, and device reachability. Stop when any of them moves. The rate limit is a ceiling, not a target.
7. Least privilege. A read-only monitoring usergroup for collectors; Settings-write only for the account that manages webhook rules.
8. Target 26.1 endpoint names now. Anything calling /statistics/bfd, /statistics/cflowd, /statistics/device or /statistics/system/stats will break on upgrade.
9. Know which deployment model you have. On-prem and Cisco-hosted control components expose the full API against your own Manager. Cisco SD-WAN Cloud (the SaaS fabric reached through an API gateway) does not expose real-time or bulk APIs and limits the rest to 5–10 requests/second.
10. Know when REST is the wrong tool. Sub-minute telemetry at scale is a job for SD-WAN telemetry data collection or the ThousandEyes Enterprise Agent, not a polling loop.
11. Start from the companion kit. A Postman/Bruno collection (40 requests across auth, inventory, bulk state, statistics, alarms, real-time, tasks) and a Python manager_client.py with all three auth modes, retry policy and paging helpers ship alongside this guide as sdwan-api-field-guide-companion.zip.
12. Don't reinvent the client. The catalystwan Python SDK, terraform-provider-sdwan, the Pulumi provider, the DevNet SD-WAN Reporting Tool and the two DevNet MCP (Model Context Protocol) servers already wrap these endpoints; Sastre handles configuration backup and restore.

Built from the Cisco DevNet Catalyst SD-WAN Manager API guides (Releases 20.18 and 26.1), the Cisco Catalyst SD-WAN Getting Started Guide, and the Cisco Control Components and Device Management Guide 26.x. Endpoint names reflect Release 26.1; verify against your Manager's /apidocs before production use.