API Documentation | Dashboard

Provides API access for creating, reading, updating and deleting Dashboards.

Note: This is currently a beta API endpoint and is subject to change without notice.

Because Dashboard objects can be fairly complex, the easiest way to understand their composition is to first create one via the UI and then click the "View API object" link and examine the contents.

Fields

_cid string
The primary key
"/dashboard/9688"
A string containing a dashboard cid
_active boolean
Whether the dashboard is active or not.
true
Either true or false
_created number
The point in time when this object was created
1471885497
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_created_by string
User who created the dashboard.
"/user/609"
A string containing a user cid
_dashboard_uuid string
Dashboard's unique UUID identifier.
"64b16e8c-fe0f-4059-beff-8d4ccd25b32c"
A string containing freeform text
_last_modified number
The point in time when this object was last updated.
1471885623
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
account_default boolean
Whether the dashboard is the default for the current account.
false
Either true or false
grid_layout object
Dashboard widget layout.
{"width":4,"height":4}
An object
height number
The number of rows in the dashboard; min: 4
A number containing an integer greater than or equal to zero
width number
The number of columns in the dashboard; min: 4, max: 26
A number containing an integer greater than or equal to zero
options object
Display options for Dashboard widgets
{"scale_text":true,"linkages":[],"fullscreen_hide_title":false,"access_configs":[{"shared_id":"fVvqyh","scale_text":true,"fullscreen":true,"text_size":16,"enabled":true,"black_dash":true,"nickname":"TestShare","fullscreen_hide_title":false}],"text_size":16,"hide_grid":false}
An object
fullscreen_hide_title boolean
Whether the title bar will be hidden when the dashboard is viewed at fullscreen; default: false
Either true or false
hide_grid boolean
Whether to hide the grid behind the widgets displaying the cell coordinates; default: false
Either true or false
scale_text boolean
Whether to auto-scale dashboard text or not (16pt at 4 columns, and text size gets smaller with more columns added); default: true
Either true or false
access_configs array

An array
object (zero or more times)
Configurations for shared dashboards with similar options to main dashboards.
An object
black_dash boolean
Whether to show the shared dashboard in black-dash mode.
Either true or false
enabled boolean
Whether this shared dashboard is valid and enabled (for temporarily disabling shares if desired).
Either true or false
fullscreen boolean
Whether to show the shared dashboard in fullscreen mode.
Either true or false
fullscreen_hide_title boolean
Whether the title bar will be hidden when the shared dashboard is viewed.
Either true or false
nickname string
Nickname for identifying this share in the UI dialog.
A string containing freeform text
scale_text boolean
Whether to auto-scale dashboard text or not.
Either true or false
shared_id string
An ID, a string that must be unique among access_configs
A string containing freeform text
text_size number
Text size (in points) to use for rendering the dashboard, if scale_text is set to false; default: 16
A number containing an integer greater than or equal to zero
linkages array
Groups linking widgets together. Currently only alerts widgets can be linked; when linked, their charts will share the same y-axis for easy visual comparison; e.g., [[ "w1", "w3" ], [ "w2", "w4" ]].
An array
array (zero or more times)
Array of widget ids to link
An array
string (one or more times)

A string containing freeform text
text_size number
The text size (in points) to use for rendering the dashboard, if scale_text is set to false; default: 16
A number containing an integer greater than or equal to zero
shared boolean
Whether the dashboard is shared; if "false", this is a private dashboard.
true
Either true or false
title string
Title of the dashboard.
"Recent Graphs and Test Graph"
A string containing freeform text
widgets array
Array of hashes defining the widgets for this Dashboard.
[{"height":2,"width":2,"settings":{"type":"graph","account_id":"968","limit":"10","search":""},"origin":"a0","widget_id":"w1","active":true,"type":"list","name":"List"},{"widget_id":"w2","type":"graph","active":true,"name":"Graph","height":2,"width":2,"settings":{"key_loc":"noop","date_window":"2w","label":"Test Graph","realtime":false,"hide_xaxis":false,"key_size":"1","period":"2000","hide_yaxis":false,"_graph_title":"Test Graph from selections","show_flags":false,"key_wrap":false,"key_inline":false,"graph_id":"be9e4f4e-7571-434a-9c05-b0185b700a4b"},"origin":"c0"}]
An array
object (one or more times)
Individual widget definition.
An object
active boolean
Whether this widget is active or not.
Either true or false
height number
How many rows this widget occupies.
A number containing an integer greater than or equal to zero
origin string
The cell ID of the left top corner of this widget.
A string containing freeform text
settings string
Specific widget settings which will vary by widget; see documentation below.
A string containing freeform text
type string
The type of widget.
A string containing either 'graph', 'chart', 'gauge', 'text', 'cluster', 'html', 'status', 'list', 'alerts' or 'forecast'
widget_id string
Widget ID for this widget. Must be unique to this dashboard. A common convention is to use 'w' + integer.
A string containing freeform text
width number
How many columns this widget occupies.
A number containing an integer greater than or equal to zero
name string
This is the "human readable" version of the widget type and must correspond to the type.
A string containing either 'Graph', 'Chart', 'Gauge', 'Text', 'Cluster', 'HTML', 'Status', 'List', 'Alerts' or 'Forecast'

Example

Fetching Dashboards

Fetching a dashboard is as simple as performing a GET on the dashboard's cid:

GET /dashboard/9688
{"widgets":[{"width":2,"height":2,"origin":"a0","settings":{"search":"","type":"graph","limit":"10","account_id":"968"},"active":true,"type":"list","widget_id":"w1","name":"List"},{"widget_id":"w2","type":"graph","active":true,"name":"Graph","height":2,"width":2,"settings":{"_graph_title":"Test Graph from selections","key_inline":false,"hide_yaxis":false,"key_wrap":false,"show_flags":false,"graph_id":"be9e4f4e-7571-434a-9c05-b0185b700a4b","hide_xaxis":false,"key_size":"1","period":"2000","label":"Test Graph","realtime":false,"date_window":"2w","key_loc":"noop"},"origin":"c0"}],"_last_modified":1471885623,"shared":true,"_dashboard_uuid":"64b16e8c-fe0f-4059-beff-8d4ccd25b32c","_created":1471885497,"_cid":"/dashboard/9688","account_default":false,"title":"Recent Graphs and Test Graph","options":{"linkages":[],"access_configs":[{"shared_id":"fVvqyh","scale_text":true,"fullscreen":true,"text_size":16,"enabled":true,"black_dash":true,"nickname":"TestShare","fullscreen_hide_title":false}],"fullscreen_hide_title":false,"hide_grid":false,"text_size":16,"scale_text":true},"grid_layout":{"width":4,"height":4},"_created_by":"/user/609","_active":true}

From this we can see:

See "Widget Layout" below to learn how to place widgets where you want them on the dashboard.

Creating Dashboards

Creating a new dashboard is as simple as making a HTTP POST request to /dashboard and passing JSON representing the new configuration:

POST /dashboard
{"grid_layout":{"width":4,"height":4},"shared":"false","widgets":[{"widget_id":"w1","active":"true","type":"status","name":"Status","height":2,"width":2,"settings":{"host_status_settings":{"layout_style":"grid","sort_by":"alerts","search":"","tag_filter_set":[]},"account_id":"968","content_type":"agent_status","agent_status_settings":{"show_agent_types":"public","show_skew":"false","show_updates":"true","search":"","show_setup":"false","show_contact":"false","show_feeds":"true"}},"origin":"a0"}],"account_default":"false","title":"List and Graph from API","options":{"fullscreen_hide_title":"false","linkages":[],"access_configs":[{"shared_id":"jx3vMf","scale_text":"false","fullscreen":"false","text_size":16,"enabled":"true","black_dash":"false","nickname":"AnotherSharedDashboard","fullscreen_hide_title":"false"},{"fullscreen_hide_title":"false","shared_id":"tmS0OR","scale_text":"false","fullscreen":"false","text_size":8,"enabled":"true","black_dash":"false","nickname":"MySharedDashboard"}],"hide_grid":"false","text_size":16,"scale_text":"true"}}

Configuring Widgets

The two key widget fields "type" and "name" define what type of widget it is. The "settings" field configures the widget; each different type of widget has its own settings that must be included.

Widget Layout

Widget layout on the Dashboard grid is determined by the grid_layout.width and grid_layout.height values along with the 'origin', 'height', and 'width" values for each widget. The grid coordinates use letters across the x-axis and numbers down the y-axis, so the top left cell is "a0" the cell to its right is "b0" and the cell below it is "a1" and so on. To create the following sample layout of four widgets (widget_ids 'w0', 'w1', 'w2', and 'w3') the corresponding widget layout fields would be as follows:

{
    .
    .
    .
    "grid_layout": {
        "height": 4,
        "width": 4
    },
    "widgets": [
        {
            "widget_id": "w0",
            "height": 3,
            "width": 3,
            "origin": "a0",
            ...
        },
        {
            "widget_id": "w1",
            "height": 1,
            "width": 1,
            "origin": "d0",
            ...
        },
        {
            "widget_id": "w2",
            "height": 3,
            "width": 1,
            "origin": "d1",
            ...
        },
        {
            "widget_id": "w3",
            "height": 1,
            "width": 3,
            "origin": "a3",
            ...
        }
    ],
    .
    .
    .
}

SAMPLE LAYOUT:
=========================================================================
‖                    widget ID 'w0'                   ‖  widget ID 'w1' ‖
‖                 |                 |                 ‖                 ‖
‖                                                     ‖                 ‖
‖      'a0'       |      'b0'       |      'c0'       ‖      'd0'       ‖
‖                                                     ‖                 ‖
‖                 |                 |                 ‖                 ‖
-  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  ===================
‖                                                     ‖  widget ID 'w2' ‖
‖                 |                 |                 ‖                 ‖
‖                                                     ‖                 ‖
‖      'a1'       |      'b1'       |      'c1'       ‖      'd1'       ‖
‖                                                     ‖                 ‖
‖                 |                 |                 ‖                 ‖
-  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
‖                                                     ‖                 ‖
‖                 |                 |                 ‖                 ‖
‖                                                     ‖                 ‖
‖      'a2'       |      'b2'       |      'c2'       ‖      'd2'       ‖
‖                                                     ‖                 ‖
‖                 |                 |                 ‖                 ‖
=======================================================  -  -  -  -  -  -
‖                    widget ID 'w3'                   ‖                 ‖
‖                 |                 |                 ‖                 ‖
‖                                                     ‖                 ‖
‖      'a3'       |      'b3'       |      'c3'       ‖      'd3'       ‖
‖                                                     ‖                 ‖
‖                 |                 |                 ‖                 ‖
=========================================================================
It is not required to fill every block defined by grid_layout.height and grid_layout.width, but widgets whose height/widget exceed the size of the grid will be visually "truncated". If your widgets don't look right on screen, or appear to be overlapping one another, be sure to check the "origin", "width", and "height" for each widget in your JSON object.

Updating Dashboards

Updating a dashboard is as simple as making a HTTP PUT request with the dashboard's cid and passing JSON representing the new configuration:

PUT /dashboard/9688
{"options":{"scale_text":true,"hide_grid":false,"text_size":16,"access_configs":[{"fullscreen_hide_title":false,"text_size":16,"enabled":true,"black_dash":false,"nickname":"TestShare","shared_id":"fVvqyh","scale_text":true,"fullscreen":false}],"linkages":[],"fullscreen_hide_title":false},"title":"Recent Graphs and Test Graph","account_default":true,"widgets":[{"widget_id":"w1","active":true,"type":"list","name":"List","height":2,"width":2,"settings":{"type":"graph","limit":"10","account_id":"968","search":""},"origin":"a0"},{"settings":{"key_size":"1","period":"2000","hide_xaxis":false,"graph_id":"be9e4f4e-7571-434a-9c05-b0185b700a4b","_graph_title":"Test Graph from selections","key_wrap":false,"show_flags":false,"key_inline":false,"hide_yaxis":false,"key_loc":"noop","date_window":"2w","realtime":false,"label":"Test Graph"},"origin":"c0","height":2,"width":2,"name":"Graph","widget_id":"w2","active":true,"type":"graph"}],"shared":true,"grid_layout":{"width":4,"height":5}}
NOTE: Be sure to include all fields when updating, even the ones that aren't being changed, or the omitted fields could be removed or replaced by default values.

Removing Dashboards

You cannot completely remove dashboards from the system, but you can hide the dashboard from the web interface and from API listings by performing a DELETE request on the dashboard cid (Doing this will also set the dashboard's "active" state to false):

DELETE /dashboard/2116