Getting Started

The following sections introduce you to the SD-WAN Manager API resources and provide instructions to make your first API request.

Cisco Catalyst SD-WAN Manager API can be categorized in the following categories:

  • Administrative and management APIs - Includes user, group and tenant management, software maintenance, backup and restore, and container management.

  • Alarm and event APIs - Includes the alarm and event notification configuration, and alarm, event, and audit log queries.

  • Configuration - Includes feature template, device template, device policy, device certificate, device action, action status, device inventory, and so on.

  • Device real-time monitoring - Includes real-time monitoring of devices, links, applications, systems, and so on.

  • Device state, statistics bulk APIs - Includes device states, aggregated statistics, and bulk queries.

  • Troubleshooting and utility - Includes HTTP status codes for errors and troubleshooting

Base URI

The system prefixes the Catalyst SD-WAN Manager API URL with /dataservice.

https://<vmanage-server>/dataservice

Except for a few file upload APIs, most of the request payloads are in JSON format.

API User Requirements

Your user role must have API access permission.

Log in with a username and password to establish a session

  • POST /j_security_check with content type x-www-form-urlencoded
  • Submit the username and password as j_username and j_password
  • The session token is in the response http cookie, JSESSIONID={session hash}.

Get a cross-site request forgery prevention token, necessary for most POST operations:

  • GET /dataservice/client/token with content type application/json
  • You need the JSESSIONID={session hash} cookie to authenticate
  • The XSRF token is in the response body
  • Use the XSRF token along with the JESSIONID cookie for ongoing API requests

Read more about authenticating, including generating an access token here.

Get the List of Devices

A simple example to illustrate the use of SD-WAN Manager API with session cookie and XSRF token is to fetch the list of devices in the fabric.

The resource URI for this is "/device", so the URL to fetch devices is https://manager>:port/dataservice/device.

  1. Authenticate to get a token (using a separate curl command)
  2. Use that token with cookie in a request to fetch device data

Here's how you can do it:


# Authenticate and get a token (replace with your credentials and server)
# This will store the cookies in cookie.txt
curl -c cookie.txt -k -X POST "https://your-manager:port/j_security_check" \
  -d "j_username=admin&j_password=your-password" \
  -H "Content-Type: application/x-www-form-urlencoded"

# Get a CSRF token (store in a variable)
TOKEN=$(curl -s -b cookie.txt -k "https://your-manager:port/dataservice/client/token" -H "Content-Type: application/json" | tr -d '"')

# Use the token and cookie to get device data
curl -s -b cookie.txt -k "https://your-manager:port/dataservice/device" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $TOKEN"

The response will be a JSON string that you can parse with tools like jq if needed:

# Format the output with jq
curl -s -b cookie.txt -k "https://your-manager:port/dataservice/device" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $TOKEN" | jq

Log Out and Destroy the Session

The logout step is important for security reasons as it properly terminates your session on the server side. This helps prevent session hijacking or unauthorized access, especially when scripts are run on shared systems. It also releases the allocated session resource.

# Logout from SD-WAN Manager
curl -b cookie.txt -k -X GET "https://your-vmanager:port/logout" \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $TOKEN"