How to use the Zenoss API

The Zenoss JSON API documentation details the routers and methods that are available. The API expects a JSON request with the following data:

action: The name of the router to handle the request e.g. DeviceRouter
method: The specific method to run e.g. addDevice
data: Arguments for the method. Data must be a JSON list [ ]. Data commonly consists of a UID of a resource, or desired keys in the response; specific arguments are in the API Documentation.
tid: The number of calls in the request. Typically will be 1.

The router you are calling should be appended to https://ZENOSS_URL/zport/dmd/. The router string appended to the URL and the router string in the action are not the same, but they are a matched pair. For example:

DeviceRouter - device_router
UsersRouter - users_router

As you can see, the action is capitalized and adjacent, while the url string is lowercased and separated by an underscore.

The -k flag is necessary to disregard the SSL certificate warning.

You can send multiple actions in one request, but they must all be to the same router. Multiple actions must be inside a JSON list, e.g. [{action, method, data, tid},{action, method, data, tid}]

Examples

Generic bash example

The following is a general purpose bash function. Note that in this case, the -d argument is surrounded by double quotes to allow the use of environment variables, while in the subsequent specific examples, single quotes are used to avoid having to escape all the double quotes.

# Your Zenoss server settings.
ZENOSS_URL="http://localhost:8080"
ZENOSS_USERNAME="admin"
ZENOSS_PASSWORD="zenoss"

# Generic call to make Zenoss JSON API calls easier on the shell.
# example: zenoss_api device_router DeviceRouter getGraphDefs '{"uid":"/zport/dmd/Devices/Server/Linux/devices/zenosstrain6.zenoss.com","drange":129600}'
zenoss_api () {
    ROUTER_ENDPOINT=$1
    ROUTER_ACTION=$2
    ROUTER_METHOD=$3
    DATA=$4

    if [ -z "${DATA}" ]; then
        echo "Usage: zenoss_api <endpoint> <action> <method> <data>" 


        return 1
    fi

    curl \
        -u "$ZENOSS_USERNAME:$ZENOSS_PASSWORD" \
        -X POST \
        -H "Content-Type: application/json" \
        -d "{\"action\":\"$ROUTER_ACTION\",\"method\":\"$ROUTER_METHOD\",\"data\":[$DATA], \"tid\":1}" \
        "$ZENOSS_URL/zport/dmd/$ROUTER_ENDPOINT"
}

Add devices (or make changes to registered devices)

Add a device

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type:application/json' \
    -d '{"action":"DeviceRouter", "method":"addDevice", "data":[{"deviceName":"UCS_DEVICE_HOSTNAME","deviceClass":"/CiscoUCS/UCS-Manager", "collector":"localhost", "model":true, "title":"UCS_DEVICE_TITLE, "zProperties":{"zCiscoUCSManagerUser":"UCS_USERNAME", "zCiscoUCSManagerPassword":"UCS_PASSWORD", "zCiscoUCSManagerUseSSL":true, "zCiscoUCSManagerUserPort":443}}], "tid":1}' \
    'https://ZENOSS_URL/zport/dmd/device_router'

Add multiple devices in one request. Note that the argument to -d is a list of actions

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type:application/json' \
    -d '[{"action": "DeviceRouter", "method": "addDevice", "data": [{"deviceName": "UCS_DEVICE_HOSTNAME", "deviceClass": "/CiscoUCS/UCS-Manager", "collector": "localhost", "model": true, "title": "UCS_DEVICE_TITLE", "zProperties": {"zCiscoUCSManagerUser": "UCS_USERNAME", "zCiscoUCSManagerPassword": "UCS_PASSWORD", "zCiscoUCSManagerUseSSL": true, "zCiscoUCSManagerUserPort": 443}}], "tid": 1}, {"action": "DeviceRouter", "method": "addDevice", "data": [{"deviceName": "UCS_DEVICE_HOSTNAME", "deviceClass": "/CiscoUCS/UCS-Manager", "collector": "localhost", "model": true, "title": "UCS_DEVICE_TITLE", "zProperties": {"zCiscoUCSManagerUser": "UCS_USERNAME", "zCiscoUCSManagerPassword": "UCS_PASSWORD", "zCiscoUCSManagerUseSSL": true, "zCiscoUCSManagerUserPort": 443}}],"tid": 2}]' \
    'https://ZENOSS_URL/zport/dmd/device_router'

Inventory  

Get all devices:

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"action":"DeviceRouter","method":"getDevices","data":[], "tid":1}' \
    'https://ZENOSS_URL/zport/dmd/device_router'

Get all devices in the /CiscoUCS/UCS-Manager Device Class:

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"action":"DeviceRouter","method":"getDevices","data":["uid":"/zport/dmd/Devices/CiscoUCS/UCS-Manager"], "tid":1}' \
    'https://zenoss_url/zport/dmd/device_router'

Edit device description field

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"action": "DeviceRouter", "method": "setInfo", "data": [{"uid":"/zport/dmd/Devices/Server/Windows/devices/SERVER/os/interfaces/VMware Accelerated AMD PCNet Adapter","description":"test"}], "tid":1' \
    'https://zenoss_url/zport/dmd/device_router'

Configuring UCSPM

Get all triggers

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"action":"TriggersRouter","method":"getTriggers","data":[{}], "tid":1}' \
    'https://ZENOSS_URL/zport/dmd/Events/triggers_router'

Get thresholds

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"action":"TemplateRouter","method":"getThresholds","data":[{"uid":"zport/dmd/Devices/CiscoUCS/rrdTemplates/UCSEthPort"}], "tid":1}' \
    'https://ZENOSS_URL/zport/dmd/template_router'

Get Events

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type:application/json' \
    -d '{"action":"EventsRouter","method":"query","data":[{"uid":"/zport/dmd","params":{"eventState":[0,1],"severity":[5,4,3,2],"tags":[],"excludeNonActionables":false},"keys":["eventState","severity","device","component","eventClass","summary","firstTime","lastTime","count","ownerid","DeviceClass","evid","eventClassKey","message"],"page":1,"start":0,"limit":200,"sort":"severity","dir":"DESC"}],"type":"rpc","tid":183}' \
    "https://ZENOSS_URL/zport/dmd/Events/evconsole_router"

Get Users

curl \
    -k \
    -u 'ZENOSS_USERNAME:ZENOSS_PASSWORD' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"action":"UsersRouter","method":"getUsers","data":[{}], "tid":1}' \
    'https://zenoss5.ucspm/zport/dmd/users_router'