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:

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:

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'