Cisco Catalyst Center API

Foundations

Overview and the four interfaces

Catalyst Center exposes a northbound REST (Representational State Transfer) API over HTTPS with JSON bodies, called the Intent API. Around it sit an eastbound event channel, a westbound ITSM (IT Service Management) integration, and a southbound multivendor SDK (Software Development Kit) that Cisco has deprecated. Every call goes to https://<cluster> plus a path prefix.

Naming shifted in 2.3.7: older operations use hyphenated singular paths (/network-device); newer ones use camelCase collections with /count and /query siblings (/networkDevices, /networkDevices/query). Prefer the newer form; the older ones are the usual deprecation candidates.

Foundations

Where a call stops

Most reads are answered from the controller's own stores and never touch a device. Writes and live CLI (command-line interface) queries become tasks, and only tasks reach devices. Cost, freshness and safety all follow from which path you hit.

Live simulation: a day of API traffic

The same three stores, running. Devices stream telemetry into Assurance without any API call. Your dashboard polls every five minutes, a CMDB (configuration management database) sync pages through inventory nightly, and webhooks leave the event engine without touching the API gateway. Trigger a Command Runner job or a 60-call bulk script to see the default limit of 50 calls per minute reject the overflow with HTTP 429.

Foundations

Authentication and RBAC

Authenticate once with HTTP Basic (RFC 7617), then send the returned JWT (JSON Web Token) in X-Auth-Token on every call for up to one hour. Every call is then checked against the caller's RBAC (Role-Based Access Control) role.

# catalyst_client.py: token cache, 401 re-auth, 429 backoff, task poller, pager
import json, time, requests
from requests.auth import HTTPBasicAuth

class CatalystCenter:
    def __init__(self, host, user, password, verify=True):
        self.base = f"https://{host}"
        self.s = requests.Session(); self.s.verify = verify
        self.auth = HTTPBasicAuth(user, password); self.exp = 0

    def _login(self):
        r = self.s.post(f"{self.base}/dna/system/api/v1/auth/token", auth=self.auth)
        r.raise_for_status()
        self.s.headers.update({"X-Auth-Token": r.json()["Token"],
                               "Content-Type": "application/json"})
        self.exp = time.time() + 55 * 60          # token lives 60 min

    def call(self, method, path, **kw):
        if time.time() > self.exp:
            self._login()
        delay, relogged = 2, False
        for _ in range(6):
            r = self.s.request(method, self.base + path, **kw)
            if r.status_code == 401 and not relogged:
                self._login(); relogged = True; continue
            if r.status_code in (429, 503):       # no rate-limit headers: back off
                time.sleep(delay); delay = min(delay * 2, 60); continue
            r.raise_for_status()
            return r.json() if r.content else {}
        raise RuntimeError(f"gave up: {method} {path}")

    def wait_task(self, task_id, timeout=900, every=5):
        t0 = time.time()
        while time.time() - t0 < timeout:
            t = self.call("GET", f"/dna/intent/api/v1/task/{task_id}")["response"]
            if t.get("endTime"):
                if t.get("isError"):
                    raise RuntimeError(t.get("failureReason"))
                return t
            time.sleep(every)
        raise TimeoutError(task_id)

    def pages(self, path, params=None, limit=500):
        offset = 1                                 # offset is 1-based
        while True:
            rows = self.call("GET", path, params={**(params or {}),
                             "offset": offset, "limit": limit})["response"]
            yield from rows
            if len(rows) < limit:
                return
            offset += limit

Foundations

Async tasks, pagination, rate limits

Every write is a task

A 202 Accepted means the request was queued, not that it worked. Poll the task until endTime is set and check isError. Orchestration (business) APIs such as SD-Access return executionId and executionStatusUrl instead; poll /dna/intent/api/v1/dnacaap/management/execution-status/{executionId}.

Pagination and filtering

Rate limits

Automate

Sites and network settings Writes config (async)

From 2.3.7.6 the site hierarchy and per-site settings moved to a new resource model. Build a site in five steps; the first three only change design intent in the controller, the last two reach devices.

Automate

Inventory, discovery and onboarding Stops at the controller Reaches the device

Inventory reads come from the controller database. Discovery, PnP (Plug and Play) claims and resyncs make the controller talk to devices.

Automate

Templates and provisioning Writes config (async) Reaches the device

Configuration templates (CLI or Velocity/Jinja) are the main way to push custom configuration in both fabric and non-fabric networks. The safe sequence is author, version, preview, then deploy.

1. Create a project and template in Template Programmer
2. Commit a version (deployments use committed versions)
3. Preview the rendered config for one device
4. Deploy to devices or by site; get a task
5. Poll the task, then run compliance

Template deployment is tracked by a deployment ID and its own status endpoint, not by the generic task API. Template variables are usually filled from a CMDB or IPAM record. Keep templates idempotent and avoid lines that the controller's own intent also writes, or compliance will flag drift.

Automate

Software images (SWIM) Writes config (async) Reaches the device

From 3.1.3, SWIM moved to the networkDeviceImages family with readiness checks, custom validations and bulk operations. The v1 image/distribution and image/activation/device operations are Sunset.

# 1. Who is off the golden image?  2. readiness  3. bulk distribute  4. bulk activate
offenders = list(cc.pages("/dna/intent/api/v1/networkDeviceImages"))
for dev in offenders:
    cc.call("POST", f"/dna/intent/api/v1/networkDeviceImages/{dev['id']}/readinessChecks")
# Build the bulk body from the operation schema for your release
t = cc.call("POST", "/dna/intent/api/v1/networkDeviceImages/distribute/bulk", json=dist_body)
cc.wait_task(t["response"]["taskId"], timeout=3600)
# ...change window opens...
t = cc.call("POST", "/dna/intent/api/v1/networkDeviceImages/activate/bulk", json=act_body)
cc.wait_task(t["response"]["taskId"], timeout=5400)
results = cc.call("GET", "/dna/intent/api/v1/networkDeviceImages/validationResults")

Automate

Fabric vs non-fabric: same API?

Yes for the platform, no for the overlay. Authentication, sites and settings, inventory, discovery, PnP, templates, SWIM, compliance, Assurance and events are the same operations in both. SD-Access adds its own domains for the fabric overlay, and wireless splits into a non-fabric and a fabric family.

Automate

SD-Access fabric Writes config (async) Reaches the device

Use the /dna/intent/api/v1/sda/... family. The older /business/sda/... operations (fabric, fabric-site, edge, border, control-plane device, virtual network, multicast) are deprecated.

Before scripting a role, check the device and release in the SD-Access compatibility matrix (see Compatibility matrix). Example from the matrix: C9350 in the edge role needs its control-plane node on IOS XE 17.18.5 and does not support IPv6.

Automate

Wireless Writes config (async)

On IOS XE 17.18.2 and later, 802.11be ofdma* and muMimo* parameters are ignored at provisioning. 3.3.1 removed fields from wireless PDC and MDC operations; retest wireless automation after upgrading.

Observe

How to choose

Pick the API family by the question, not by the endpoint you already know.

Observe

Customer questions to endpoints

NOC (Network Operations Center), helpdesk and security teams ask in business terms. This table maps the question to the scalable endpoint and to the heavier troubleshooting-only alternative.

PSIRT is Cisco's Product Security Incident Response Team. Push beats poll: subscribe to issue and event webhooks instead of looping on /issues.

Observe

Health, issues and Assurance events Stops at the controller

Observe

Events and webhooks Stops at the controller

When a subscribed event fires, Catalyst Center makes an HTTP POST or PUT to your listener with a JSON payload. Destinations can be REST webhook, email, syslog, SNMP trap or Webex (listed in the 3.3.x Platform User Guide), plus ITSM. Event definitions are fixed and cannot be edited.

# Illustrative payloads: confirm field names in Platform > Developer Toolkit > APIs
hook = cc.call("POST", "/dna/intent/api/v1/event/webhook", json={
    "name": "noc-listener", "description": "NOC event intake",
    "url": "https://hooks.example.com/catc", "method": "POST",
    "trustCert": True})
cc.call("POST", "/dna/intent/api/v1/event/subscription/rest", json=[{
    "name": "network-device-unreachable",
    "subscriptionEndpoints": [{"instanceId": WEBHOOK_ID,
        "subscriptionDetails": {"connectorType": "REST"}}],
    "filter": {"eventIds": ["NETWORK-DEVICES-3-506"]}}])

# Hourly reconcile: pull what the webhook may have missed
events = cc.call("GET", "/dna/data/api/v1/assuranceEvents",
                 params={"deviceFamily": "Switches and Hubs",
                         "startTime": int((time.time() - 3600) * 1000)})

Cisco's stated practice: confirm HTTP/HTTPS reachability from the cluster to your listener before subscribing. An HTTP/S proxy can be set for outbound notifications. The event ID above is an example; pick IDs from Platform > Developer Toolkit > Event Notifications > Event Catalog.

Observe

Troubleshooting tools Reaches the device

Command Runner runs read-only CLI commands on devices; Path Trace (POST /pathTraces from 3.2.2, POST /flow-analysis earlier) analyses the path between two endpoints. Both are tasks that reach devices: run them for one device or flow, on demand, never on a schedule.

cc = CatalystCenter("catc.example.com", "svc-api", "***")
ids = [d["id"] for d in cc.pages("/dna/intent/api/v1/network-device",
                                 {"platformId": "C9300-48P"})]
job = cc.call("POST", "/dna/intent/api/v1/network-device-poller/cli/read-request",
              json={"commands": ["show version", "show ip int brief"],
                    "deviceUuids": ids[:10], "timeout": 0})
task = cc.wait_task(job["response"]["taskId"])
file_id = json.loads(task["progress"])["fileId"]
output = cc.call("GET", f"/dna/intent/api/v1/file/{file_id}")

Integrate

ITSM and ServiceNow

ITSM integration ships as pre-built bundles configured in the GUI. Add the ITSM instance at System > Settings > Destinations > ITSM, test connectivity, then enable bundles under Platform > Manage > Bundles.

Platform > Runtime Dashboard shows call counts and durations for the ServiceNow integration only. A "post to staging table" destination sends raw data to any REST endpoint for your own scripts.

Integrate

Integration playbooks

Six patterns cover most customer integrations. Each lists the flow in order and the most expensive mistake to avoid.

Integrate

AI agents and MCP

Cisco's open-source Catalyst Center MCP server, in beta since August 2026, lets any MCP-capable AI client call generated Catalyst Center API tools. It runs inside your network, so data and the model can stay within an air-gapped boundary.

When to use MCP vs the AI Assistant

Cisco's rule: use the in-product AI Assistant when the work starts in the Cisco product; use MCP when the work starts in a workflow you are building around it, such as a helpdesk tool, self-service portal, cross-vendor copilot, automated report or custom agent.

MCP best practices

1. It is not read-only by design. The README states the server adds no authorization layer, does not enforce read-only, and the catalog may include configuration-changing operations. Enforce read-only with an Observer-role account.
2. One dedicated, least-privilege account per deployment. Treat every connected client as able to call anything that account can.
3. Keep the endpoint private. Bind to 127.0.0.1; if shared, put it behind your gateway with authentication and TLS.
4. Keep certificate verification on (CATALYST_CENTER_VERIFY_SSL=true) except in labs.
5. Match the release branch to the controller and rebuild after each controller upgrade.
6. State the safety boundary in prompts ("read-only, do not change anything"). It is a backstop, not a control.
7. Mind rate limits. Agents chain many calls; the same per-operation limits and 500-row pages apply.
8. Choose the model deliberately. For regulated or air-gapped sites, pair the local server with an approved private model.
9. Log tool calls on your side. The controller sees only one service account.
10. Beta can change. Pin a commit and retest on updates.

# Run the official server on loopback with a read-only (Observer) account
git clone https://github.com/cisco-en-programmability/catc-mcp-oss && cd catc-mcp-oss
git checkout release/<M.N.P.Q>            # match your Catalyst Center release
export CATALYST_CENTER_HOST="https://catalyst-center.example.com"
export CATALYST_CENTER_USERNAME="mcp-observer"
export CATALYST_CENTER_PASSWORD="***"
export CATALYST_CENTER_VERIFY_SSL=true
docker build -t catalyst-center-mcp:local .
docker run --rm -p 127.0.0.1:7001:7001 -e CATALYST_CENTER_HOST \
  -e CATALYST_CENTER_USERNAME -e CATALYST_CENTER_PASSWORD \
  -e CATALYST_CENTER_VERIFY_SSL catalyst-center-mcp:local
curl http://localhost:7001/v1/health      # process up
# Claude Desktop: {"mcpServers": {"catalyst-center": {"url": "http://localhost:7001/v1/mcp"}}}

Companion: the DevNet Content Search MCP (https://devnet.cisco.com/v1/foundation-search-mcp/mcp) searches Catalyst Center and Meraki API documentation; it has no live network data. Community MCP servers exist but are not Cisco-supported.

Operate

Change prerequisites: fabric and non-fabric

Most failed API changes trace back to a device that was not in a clean state before the change. Gate every automated change on the checks below. Items marked "practice" are general engineering practice; the rest map to documented Catalyst Center features.

Before any change (both)

Additional checks for SD-Access

Additional checks for non-fabric

After the change (both)

1. Task or execution status succeeded
2. Post-checks or validation results match pre-checks
3. Run compliance on targets
4. Site and device health unchanged or better
5. Close the change with evidence

Operate

Compatibility matrix

Cisco's Catalyst Center compatibility matrix lists which devices each release supports, with an SD-Access mode and a Non-Fabric mode, filters by device role (ISE, fabric edge, border and control plane, wireless, extended node), and an upgrade-path view. It is a web page with a JSON download, not an API.

Load the matrix's JSON download into your pipeline as a static gate, refreshed per release. Recommended device software versions come from the Cisco Software Download page.

Operate

Errors and resilience

Operate

2.3.7.x to 3.x deltas

2.3.7.x is the long-lived train many customers still run, and it received 2.3.7.10 in August 2025 alongside 3.1.x. An integration written on 2.3.7.x keeps working on 3.x except where it uses deprecated operations; the gains in 3.x are mostly new API families.

What is new in 3.2.x and 3.3.1

DevNet's full reference stops at 3.1.6, so these come from the Platform User Guides 3.2.x and 3.3.x. Neither guide lists any deprecated API operation or breaking change for 3.2.2, 3.2.3 or 3.3.1. Release 3.2.2 shipped as controlled availability; 3.3.1 marks some operations BETA in the catalog and in the spec's banner field.

Operate

Deprecated and sunset APIs

Deprecated means a better alternative exists. Sunset means support ends once the deprecation period elapses. A deprecated operation stays for two GA (Generally Available) releases or one year, whichever is longer; after that Cisco may remove it in any release.

Many tutorials still use legacy paths. For example, a September 2025 Cisco Community lab creates sites with POST /dna/intent/api/v1/site and credentials with /v2/global-credential; both work on older releases but the site path is deprecated. Translate examples to the replacement column before reuse.

Behaviour changes without a path change: 3.1.5 raised the minimum resync to 6 hours and made system performance APIs ignore time parameters; 3.1.6 ignores some 802.11be parameters on IOS XE 17.18.2+; 3.3.1 removed wireless PDC and MDC fields. For a definitive list on your build, filter the in-product API catalog by Deprecated and Sunset banners.

Operate

Tooling

Operate

Guidance checklist

1. Pin to your release. API version equals controller version; pin SDK, Ansible and Terraform to it.
2. Read Deprecated and Breaking sections before every upgrade, then test integrations against the target release in a lab.
3. One service account per integration, least privilege, RBAC v2 roles and access groups.
4. Cache the token and re-authenticate once on 401; documented lifetimes differ (1 hour vs 60 seconds).
5. Keep TLS verification on in production.
6. Treat 202 as accepted, not done. Poll the task with a timeout and surface failureReason.
7. Page at 500 with a 1-based offset; size with /count, filter with /query, de-duplicate by ID.
8. Design for 429. Per-operation limits of 50 to 100 per minute; back off and serialize writes.
9. Push, don't poll. Webhooks for events and issues; reconcile hourly.
10. Never schedule device-touching calls. Command Runner and Path Trace are on demand, one device at a time.
11. Prefer the new resource model: /sites, /ipam, /sda, /networkDevices, /networkDeviceImages.
12. Gate every change on prerequisites: backup, archive, Managed and Reachable, no critical issues, compatibility.
13. Use bulk operations in waves by site.
14. Validate before and after: readiness checks, validation workflows, compliance, health.
15. Put MCP behind an Observer account on loopback. The server does not enforce read-only.

Operate

Figure index

Every diagram in the guide. Flow figures animate their packets (pause or replay from the bar above each one); step-through figures send a packet as you advance.

1. Figure 0Integration directionsOverview and interfaces
2. Figure 1Where a call stopsWhere a call stops
3. Figure 1bLive simulation of a day of API trafficWhere a call stops
4. Figure 2Token authentication and re-authenticationAuthentication and RBAC
5. Figure 3Asynchronous task patternAsync, paging, limits
6. Figure 4Day-0 site buildSites and settings
7. Figure 5SWIM upgrade waveSoftware images (SWIM)
8. Figure 6SD-Access fabric build orderSD-Access fabric
9. Figure 7Choosing the right data sourceHow to choose
10. Figure 8Webhooks with hourly reconcileWebhooks
11. Figure 9Command Runner round tripTroubleshooting tools
12. Figure 10ServiceNow ITSM integrationITSM and ServiceNow
13. Figure 11MCP server trust boundaryAI agents and MCP
14. Figure 12Retry decision by status codeErrors and resilience
15. Figure 13Separating failures from filter or RBAC scopeErrors and resilience
16. Figure 14Release and deprecation timelineDeprecated APIs

Operate

Sources

• DevNet: Catalyst Center API overview
• DevNet: Getting Started (3.1.6)
• DevNet: API changelog
• DevNet: Authentication
• DevNet: Asynchronous operations
• DevNet: API versioning and deprecation
• DevNet: Event management
• DevNet: Command Runner guide
• DevNet: Ansible for Catalyst Center
• Cisco: Release notes index
• Cisco: Release notes 3.2.3
• Cisco: Platform User Guide 3.2.x
• Cisco: Platform User Guide 3.3.x (PDF)
• Cisco: Catalyst Center compatibility matrix (SD-Access)
• Cisco: ServiceNow CMDB synchronization
• Cisco tech note 226435: Understand and use Catalyst Center APIs
• Cisco: Platform User Guide 3.3.x, About Intent APIs
• Cisco: Platform User Guide 3.3.x, API prerequisites
• Cisco: Platform User Guide 3.3.x, APIs and event notifications chapter
• Cisco Community: Working with Catalyst Center API
• PyPI: catalystcentersdk
• Red Hat: cisco.catalystcenter collection
• GitHub: catc-mcp-oss
• Cisco Blogs: Meraki and Catalyst Center MCP servers

Payloads marked illustrative must be checked against the operation schema in your release. Verify endpoints in Platform > Developer Toolkit > APIs before production use.