Server Density API Docs

Suggest Edits

Getting a token via the API

If you need to generate tokens programmatically, you can request a token through the API with your username and password. All future requests can then be performed using the returned token.

If the user generating the token has Multi Factor Authentication enabled, you cannot use this method and must create the token via the web UI.

 
posthttps://api.serverdensity.io//tokens
curl -v https://api.serverdensity.io/tokens/ \
     --data username=llama \
     --data password=securepassword \
     --data tokenName=Llama+script \
     --data accountName=example 
import json
import requests

user_payload = {
    "username": "llama",
    "password": "securepassword",
    "accountName": "example",
    "tokenName": 'Llama script',
}

token_data = requests.post(
    'https://api.serverdensity.io/tokens/',
    headers={
        "content-type": "application/json"
    },
    data=json.dumps(user_payload)
)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "token_data": {
        "userId": "51f65a19dba4bbf15d000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "date_issued": {
            "sec": 1375106903,
            "usec": 49000
        },
        "tokenName": "Llama script",
        "token": "b97da80a41c4f61bff05975ee51eb1aa"
    }
}

Body Params

username
string
required

The token will be associated with this username

password
string
required

The token will be associated with this password

accountName
string
required

The Server Density account that the user is a member of e.g. if you log in at example.serverdensity.io your accountName is example

tokenName
string
required

The name of the token, displayed in the UI

 
Suggest Edits

Deleting a token via the API

API tokens can be deleted via the API or through the web UI.

 
deletehttps://api.serverdensity.io//tokens/token_to_delete
curl -v -X DELETE https://api.serverdensity.io/tokens/901de5c241a6e879c1c6f0b27459d3f1?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token_to_delete = '901de5c241a6e879c1c6f0b27459d3f1'

delete_response = requests.delete(
    "https://api.serverdensity.io/tokens/{0}".format(token_to_delete),
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa'
    }
)
require "httparty"

token_to_delete = "901de5c241a6e879c1c6f0b27459d3f1"
current_token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token_to_delete},
}

response = HTTParty.delete("https://api.serverdensity.io/tokens/#{token_to_delete}", params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "token": "901de5c241a6e879c1c6f0b27459d3f1"
}

Path Params

token_to_delete
string
required

The token you want to delete, as part of the URL

Body Params

token
string
required

Your API token

 

In this example, the tokens are different but they can be the same if you want to delete the token you’re accessing the API with.

Suggest Edits

Getting a token via the UI

As well as programmatically, it's also possible to create tokens manually within your user interface.

 
  1. Log in to your Server Density account.
  2. Click your name in the top left, then click Security.
  3. Under API tokens, enter a name for the API application you're building so you can easily recognise it in the future e.g. "Llama Script".
  4. Press Enter and your API token will be shown as a 32 character ID.
Suggest Edits

Pagination

Our API will not return more than 400 JSON objects in a single request. Therefore we provide pagination to access more data conveniently. For data where pagination is required additional headers will be included in the response.

 
gethttps://api.serverdensity.io//?perPage=10&page=4
curl -v -X GET "https://api.serverdensity.io/inventory/tags?perPage=10&page=4&token=b97da80a41c4f61bff05975ee51eb1aa"
import requests

r = requests.get('https://api.serverdensity.io/inventory/tags',
    params = {
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
        'perPage': '10',
        'page': '4'
    }
)
require "httparty"

token = 'b97da80a41c4f61bff05975ee51eb1aa'
params = {
    :query => {
        "token" => token,
        "perPage" => "10",
        "page" => "4"
    }
}

r = HTTParty.get('https://api.serverdensity.io/inventory/tags', params)
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
devices = client.devices.list(perPage=10, page=4)

# This works for all list endpoints. 

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
< x-last-page: http://api.serverdensity.io/inventory/tags?page=106&perPage=5
< x-total-number: 529
< x-first-page: http://api.serverdensity.io/inventory/tags?page=1&perPage=5
< x-previous-page: http://api.serverdensity.io/inventory/tags?page=3&perPage=5
< x-next-page: http://api.serverdensity.io/inventory/tags?page=5&perPage=5

Query Params

perPage
string

Maximum number of objects to include in response

page
string

Request a specific page number

 

Response Headers

x-total-number Gives the total number of results available
x-first-page Gives the URL for the first page of paginated results
x-last-page Gives the URL for the last page of paginated results
x-previous-page Gives the URL for the previous page of paginated results
x-next-page Gives the URL for the next page of paginated results

Pagination is designed to work with any API endpoint that returns are large amount of data. Simply append the pagination options to your endpoint URL.

Suggest Edits

Creating a device

You can create new devices via the API, useful if you want to automatically provision new devices and start monitoring automatically.

This API method is used by our Puppet manifest, Chef cookbook and installer shell script to automatically create devices during the agent installation.

 
posthttps://api.serverdensity.io//inventory/devices
curl -v -X POST https://api.serverdensity.io/inventory/devices/?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=Llama
import requests

api_response = requests.post(
    'https://api.serverdensity.io/inventory/devices/',
    params={
        'token':'b97da80a41c4f61bff05975ee51eb1aa'
    },
    data={
        "name": "Llama"
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token},
    :body => {"name" => "Llama"}
}

response = HTTParty.post("https://api.serverdensity.io/inventory/devices/", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$device = array("name"=> "Llama");

$client->api('devices')->create($device);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
device = client.devices.create(data={'name': 'devicename')
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f7eafcdba4bb235e000ae4",
    "name": "Llama",
    "type": "device",
    "agentKey": "c2bbdd6689ff46282bdaa07555641498",
    "group": null,
    "publicIPs": ["192.91.9.2", "129.812.831.1"],
    "privateIPs": ["127.0.0.1"],
    "updatedAt": "2016-02-30T16:34:04",
    "createdAt": "2016-02-30T16:34:04",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "deleted": false,
    "tags": null,
}

Body Params

token
string
required

Your API token.

name
string
required

Name of device.

cpuCores
string

Item’s number of cores.

group
string

Name of group. This is set to “null” when a device doesn’t have a group.

installedRAM
string

RAM installed

os
string

A dictionary containing code and name. OS codes can be seen below

privateIPs
array of strings

Item’s private IP addresses as a JSON encoded list.

publicIPs
array of booleans

Item’s public IP addresses as a JSON encoded list.

location
string

A dictionary containing countryCode, text (which is the city) and countryName

swapSpace
string

Item’s swap space

provider
string

The provider dependent string that identifies this item. If this field is set, provider is mandatory.

tags
array of booleans

A JSON list of tag IDs.

 

Optional Parameters

Optional parameters will create more metadata for the device.

OS Codes

Code OS
mac Mac OSX
linux Linux
windows Windows
freebsd FreeBSD
Suggest Edits

Deleting a device

Delete a device from your account. Device deletion is an irreversible process when carried out by the API.

 
deletehttps://api.serverdensity.io//inventory/devices
curl -v -X DELETE https://api.serverdensity.io/inventory/devices/51f931c9dba4bba36d001542?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
device_id = '51f931c9dba4bba36d001542'

delete_response = requests.delete(
    "https://api.serverdensity.io/inventory/devices/{0}".format(device_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
device_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete("https://api.serverdensity.io/inventory/devices/#{device_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$device = "id here";

$client->api('devices')->delete($device);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
device_id = '51f931c9dba4bba36d001542'


client = ApiClient(token)
device = client.devices.delete(id=device_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f931c9dba4bba36d001542"
}

Body Params

token
string
required

Your API token.

deviceId
string
required

The ID of your device.

 
Suggest Edits

Listing all devices

List each device on your account, along with the meta data.

 
gethttps://api.serverdensity.io//inventory/devices
curl -v -X GET https://api.serverdensity.io/inventory/devices?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"

r = requests.get(
    'https://api.serverdensity.io/inventory/devices',
    params = {
        'token': token 
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/devices", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('devices')->all();

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
device = client.devices.list()
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "51f6585e11f144673749afbb",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "agentKey": "22ddab237dff5cde07dc70a26e93c262",
        "agentVersion": "2.0.3", 
        "cId": "c16",
        "cloud": false,
        "cpuCores": null,
        "createdAt": "2016-02-29T12:19:11",
        "deleted": false,
        "group": "docs",
        "hostname": "docshost",
        "imageId": null,
        "installedRAM": "",
        "ip": null,
        "isMonitored": true,
        "isNew": true,
        "lastPayloadAt": {
            "sec": 1375179061,
            "usec": 0
        },
        "location": {
            "countryCode": "gb",
            "countryName": "United Kingdom",
            "text": "Docs device"
        },
        "name": "Llama",
        "os": {
            "code": "linux",
            "name": "Linux"
        },
        "pluginsEnabled": [
            {
                "DocsPlugin": [
                    "hats",
                    "socks",
                    "jumpers"
                ]
            },
            {
                "TestPlugin": [
                    "test1",
                    "test3",
                    "test2"
                ]
            }
        ],
        "privateIPs": [],
        "provider": null,
        "publicIPs": [],
        "status": null,
        "swapSpace": "",
        "CPUCores": "",
        "type": "device",
        "updatedAt": "2016-02-30T10:11:01",
        "userId": "507ec4f48f4a5c547f000000",
        "tags": null,
    }
]

Query Params

token
string
required

Your API token

 

The deleted field can be either set to true or false. If a cloud-synced device is deleted using the web front end it will still appear in the api call, but with deleted set to true.

Suggest Edits

Searching for a device

There is a single resources endpoint that will search the entire inventory. This can be used to search for services too.

 
gethttps://api.serverdensity.io//inventory/resources
curl -v -X GET https://api.serverdensity.io/inventory/resources?token=b97da80a41c4f61bff05975ee51eb1aa\&filter='\{"name":"Llama","type":"service"\}'\&fields='\["name","type","_id"\]'
import requests
import json

api_response = requests.get(
    'https://api.serverdensity.io/inventory/resources',
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
        'filter': json.dumps(
            {
                'name':'Llama',
                'type': 'service'
            }
        ),
        'fields': json.dumps(
            [
                'name',
                'type',
                '_id'
            ]
        )
    }
)
require "httparty"
require "json"

token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token 
    "filter" : JSON.dump({
            :name => 'docs',
            :type => 'service'
        }),
        'fields': JSON.dump({
            [
                'name',
                'type',
                '_id'
            ]
        })
    }
}
response = HTTParty.get('https://api.serverdensity.io/inventory/resources', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$filter = array(
    "name" => "docs",
    "type" => "service"
);
$fields = array("name", "type", "_id");
$client->api('services')->search($filter, $fields);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

filter =  {
    'name':'Llama',
    'type': 'service'
}
fields = ['name', 'type', '_id']

client = ApiClient(token)
device = client.devices.search(filtering=filter, fields=fields)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "51f6585e11f144673749afbb",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "currentStatus": "up",
        "body": [],
        "name": "Llama",
        "slowThreshold": 500,
        "timeout": 10,
        "checkType": "HTTP",
        "checkUrl": "http://example.org",
        "checkMethod": "GET",
        "checkLocations": [
            "dub"
        ],
        "notes": "",
        "group": null,
        "type": "service",
        "updatedAt": "2016-02-31T13:59:34",
        "createdAt": "2016-02-31T13:59:34",
        "deleted": false, 
        "headers": [], 
        "validateCert": false,
        "tags": null,
    }
]

Query Params

token
string
required

Your API token.

filter
string
required

A JSON encoded hash of the fields that you wish to search by. Any field returned can be searched on.

fields
string

A JSON encoded array of the fields that you wish returned by the call.

 

The response will either be an empty JSON array, or a list of the devices that match the filter. These will be in the same format and with the same fields as without the filter.

Suggest Edits

Updating a device

Update a device and the associated metadata.

 
puthttps://api.serverdensity.io//inventory/devices/deviceId
curl -v -X PUT https://api.serverdensity.io/inventory/devices/51f7ecd4dba4bbee5d000a74?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=Changed+Llama
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
device_id = '51f7ecd4dba4bbee5d000a74'

api_response = requests.put(
    'https://api.serverdensity.io/inventory/devices/{0}'.format(device_id),
    params={
        'token': token
    },
    data={
        "name": "Changed Llama"
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
device_id = '51f7ecd4dba4bbee5d000a74'

params = {
    :query => {"token" => token},
    :body => {"name": "Changed Llama"}
}

response = HTTParty.put("https://api.serverdensity.io/inventory/devices/#{device_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = "76oeu57a5765a76e5a7";

$fields = array(
    "name" => "Changed llama",
);
$fields = array("name", "type", "_id");
$client->api('devices')->search($id, $fields);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
_id = '2dfae5bf81f65492a40569d39b29ffa1'

client = ApiClient(token)
device = client.devices.update(
    id=_id, 
    data={'name': 'Changed llama'}
)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "Changed Llama",
    "publicIPs": [],
    "privateIPs": [],
    "updatedAt": "2016-02-31T10:36:03",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "_id": "51f7ecd4dba4bbee5d000a74"
}

Path Params

deviceId
string
required

The ID of the device to update.

Body Params

token
string
required

Your API token.

cpuCores
string

Item’s number of cores.

group
string

Name of group. This is set to “null” when a device doesn’t have a group.

hostname
string

Item’s hostname.

installedRAM
string

RAM installed.

name
string

Name of the device.

os
string

Operating system that it runs.

privateIPs
string

Item’s private IP addresses as a JSON encoded list.

publicIPs
string

Item’s public IP addresss as a JSON encoded list.

swapSpace
string

Item’s swap space.

provider
string

Provider where the item is hosted. For cloud items it may be ‘amazon’, ‘google’ or ‘rackspace’.

providerId
string

The provider dependent string that identifies this item. If this field is set, provider is mandatory.

tags
string

A JSON list of tag IDs.

 
Suggest Edits

View device by ID

 
gethttps://api.serverdensity.io//inventory/devices/deviceId
curl -v -X GET https://api.serverdensity.io/inventory/devices/51f6585e11f144673749afbb?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

device_id = '51f6585e11f144673749afbb'
token = "b97da80a41c4f61bff05975ee51eb1aa"

api_response = requests.get(
    'https://api.serverdensity.io/inventory/devices/{0}'.format(device_id),
    params = {
        'token': token
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
device_id = "22ddab237dff5cde07dc70a26e93c262"

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/inventory/devices/#{device_id}', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = "76oeu57a5765a76e5a7";

$client->api('devices')->view($id);
?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
_id = '2dfae5bf81f65492a40569d39b29ffa1'

client = ApiClient(token)
device = client.devices.view(id=_id)

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f6585e11f144673749afbb",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "agentKey": "22ddab237dff5cde07dc70a26e93c262",
    "cId": "c16",
    "cloud": false,
    "cpuCores": null,
    "createdAt": "2016-02-29T12:19:11",
    "deleted": false,
    "group": "docs",
    "hostname": "docshost",
    "imageId": null,
    "installedRAM": "",
    "ip": null,
    "isMonitored": true,
    "isNew": true,
    "lastPayloadAt": {
        "sec": 1375179061,
        "usec": 0
    },
    "location": {
        "countryCode": "gb",
        "countryName": "United Kingdom",
        "text": "Docs device"
    },
    "name": "Llama",
    "os": {
        "code": "linux",
        "name": "Linux"
    },
    "pluginsEnabled": [
        {
            "DocsPlugin": [
                "hats",
                "socks",
                "jumpers"
            ]
        },
        {
            "TestPlugin": [
                "test1",
                "test3",
                "test2"
            ]
        }
    ],
    "privateIPs": [],
    "provider": null,
    "publicIPs": [],
    "status": null,
    "swapSpace": "",
    "CPUCores": "",
    "type": "device",
    "updatedAt": "2016-02-30T10:11:01",
    "userId": "507ec4f48f4a5c547f000000",
    "tags": null,
}

Path Params

deviceId
string
required

The ID of the device to update.

Query Params

token
string
required

Your API token.

 
Suggest Edits

View device by agent key

 
gethttps://api.serverdensity.io//inventory/devices/agentKey/byagentkey
curl -v -X GET https://api.serverdensity.io/inventory/devices/22ddab237dff5cde07dc70a26e93c262/byagentkey?token=b97da80a41c4f61bff05975ee51eb1aa

import requests

agent_key = '22ddab237dff5cde07dc70a26e93c262'
token = 'b97da80a41c4f61bff05975ee51eb1aa'

api_response = requests.get(
    'https://api.serverdensity.io/inventory/devices/{0}/byagentkey'.format(agent_key),
    params={
        'token': token
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
agent_key = "22ddab237dff5cde07dc70a26e93c262"

params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/devices/#{agent_key}/byagentkey", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$agentKey = "76oeu57a5765a76e5a7";

$client->api('devices')->viewByAgent($agentKey);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
agent_key = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
device = client.devices.view_by_agent(agent_key)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f6585e11f144673749afbb",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "agentKey": "22ddab237dff5cde07dc70a26e93c262",
    "cId": "c16",
    "cloud": false,
    "cpuCores": null,
    "createdAt": "2016-02-29T12:19:11",
    "deleted": false,
    "group": "docs",
    "hostname": "docshost",
    "imageId": null,
    "installedRAM": "",
    "ip": null,
    "isMonitored": true,
    "isNew": true,
    "lastPayloadAt": {
        "sec": 1375179061,
        "usec": 0
    },
    "location": {
        "countryCode": "gb",
        "countryName": "United Kingdom",
        "text": "Docs device"
    },
    "name": "Llama",
    "os": {
        "code": "linux",
        "name": "Linux"
    },
    "pluginsEnabled": [
        {
            "DocsPlugin": [
                "hats",
                "socks",
                "jumpers"
            ]
        },
        {
            "TestPlugin": [
                "test1",
                "test3",
                "test2"
            ]
        }
    ],
    "privateIPs": [],
    "provider": null,
    "publicIPs": [],
    "status": null,
    "swapSpace": "",
    "CPUCores": "",
    "type": "device",
    "updatedAt": "2016-02-30T10:11:01",
    "userId": "507ec4f48f4a5c547f000000", 
    "tags": null
}

Path Params

agentKey
string
required

The key used by the agent

Query Params

token
string
required

Your API token.

 
Suggest Edits

Listing device groups

 
gethttps://api.serverdensity.io//inventory/devices/groups/?token=token
curl -X GET https://api.serverdensity.io/inventory/devices/groups/?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"

r = requests.get(
    'https://api.serverdensity.io/inventory/devices/groups',
    params = {
        'token': token 
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/devices/groups", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('devices')->deviceGroups();

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    "Group1", 
    "Group2", 
    "Group3"
]

Path Params

token
string
required

Your API token

 
Suggest Edits

Creating a service

 
posthttps://api.serverdensity.io//inventory/services
curl -v -X POST https://api.serverdensity.io/inventory/services/?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=Llama \
     --data checkType=http \
     --data checkUrl=http:\/\/www.example.org \
     --data checkMethod=GET \
     --data timeout=10 \
     --data checkLocations='["dub"]' \
     --data slowThreshold=500
import json
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

api_response = requests.post(
    'https://api.serverdensity.io/inventory/services',
    params={
        'token': token
    },
    data={
        'name': 'Llama',
        'checkType': 'http',
        'checkUrl': 'http://www.example.org',
        'checkMethod': 'GET',
        'timeout': '10',
        'slowThreshold': '500',
        'checkLocations': json.dumps(['dub'])
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token},
    :body => {
        'name' => 'Llama',
        'checkType' => 'http',
        'checkUrl' => 'http://www.example.org',
        'checkMethod' => 'GET',
        'timeout' => '10',
        'slowThreshold' => '500',
        'checkLocations': JSON.dump(['dub'])
    }
}

response = HTTParty.post("https://api.serverdensity.io/inventory/services", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$service = array("name"=> "Llama");

$client->api('services')->create($service, ['my', 'tags']);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

data={
  'name': 'Llama',
  'checkType': 'http',
  'checkUrl': 'http://www.example.org',
  'checkMethod': 'GET',
  'timeout': 10,
  'slowThreshold': 500,
  'checkLocations': ['dub'])
}

client = ApiClient(token)
service = client.services.create(data=data)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "Llama",
    "checkType": "http",
    "checkUrl": "http://www.example.org",
    "checkMethod": "GET",
    "timeout": 10,
    "slowThreshold": 500,
    "checkLocations": [
        "dub"
    ],
    "group": null,
    "type": "service",
    "updatedAt": "2016-02-31T15:48:25",
    "createdAt": "2016-02-31T15:48:25",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "deleted": false,
    "_id": "51f931c9dba4bba36d001542",
    "tags": null,
}

Body Params

token
string
required

Your API token.

name
string
required

The display name for the service.

checkType
string
required

The type of check: either http or tcp

timeout
int32
required

How many seconds to wait until timing out. Max 30.

checkUrl
string
required

HTTP Check - The URL to issue the request to.

checkLocations
string
required

A JSON list of locations to check from e.g. ["lon", "dub"]. Each location has its own “API ID” which is noted on the locations list. Location ID's can be found on our support site

checkMethod
string
required

HTTP Check - The HTTP method used to issue the check: either GET, POST, PUT or DELETE. Required for HTTP check, irrelevant for TCP.

slowThreshold
int32
required

HTTP Check - Request time millisecond threshold after which service is deemed slow.

group
string

The group the service belongs to. If this is empty it’s set to null.

auth
string

Basic HTTP auth username and password. e.g. {"username":"Thomas", "password":"password"}

headers
string

HTTP Check - headers to include e.g. {"User-Agent": "Thomas the Tank Engine"}

body
string

HTTP Check - Content of the HTTP requestbody

validateCert
boolean

HTTP Check - Whether to validate the SSL certificate or not

host
string

TCP Check - The hostname or IP address to issue the TCP check to

port
string

TCP Check - The port number to issue the TCP check to

data
string

TCP Check - The content to send when opening the TCP socket

tags
string

A JSON list of tag IDs.

 
Suggest Edits

Deleting a service

 
deletehttps://api.serverdensity.io//inventory/services/serviceId
curl -v -X DELETE https://api.serverdensity.io/inventory/services/51f931c9dba4bba36d001542?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
service_id = '51f931c9dba4bba36d001542'

delete_response = requests.delete(
    "https://api.serverdensity.io/inventory/services/{0}".format(service_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
service_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete("https://api.serverdensity.io/inventory/services/#{service_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$service = "id here";

$client->api('services')->delete($service);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
service_id = '51f931c9dba4bba36d001542'

client = ApiClient(token)
_id = client.services.delete(_id=service_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f931c9dba4bba36d001542"
}

Path Params

serviceId
string
required

The ID of your service.

Body Params

token
string
required

Your API token.

 
Suggest Edits

Listing services

 
gethttps://api.serverdensity.io//inventory/services
curl -v -X GET https://api.serverdensity.io/inventory/services?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

r = requests.get(
    'https://api.serverdensity.io/inventory/services',
    params={'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/services", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('services')->all();

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
services = client.services.list()
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "51f6585e11f144673749afbb",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "currentStatus": "up",
        "body": [],
        "name": "Llama",
        "slowThreshold": 500,
        "timeout": 10,
        "checkType": "HTTP",
        "checkUrl": "http://example.org",
        "checkMethod": "GET",
        "checkLocations": [
            "dub"
        ],
        "notes": "",
        "group": null,
        "type": "service",
        "updatedAt": "2016-02-31T13:59:34",
        "createdAt": "2016-02-31T13:59:34",
        "deleted": false, 
        "headers": [], 
        "validateCert": false, 
        "tags": null,
    }
]

Query Params

token
string
required

Your API token.

 
Suggest Edits

Searching for a service

There is a single resources endpoint that will search the entire inventory. This can be used to search for devices too.

 
gethttps://api.serverdensity.io//inventory/resources
curl -v -X GET https://api.serverdensity.io/inventory/resources?token=b97da80a41c4f61bff05975ee51eb1aa\&filter='\{"name":"Llama","type":"service"\}'\&fields='\["name","type","_id"\]'
import requests
import json

api_response = requests.get(
    'https://api.serverdensity.io/inventory/resources',
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
        'filter': json.dumps(
            {
                'name':'Llama',
                'type': 'service'
            }
        ),
        'fields': json.dumps(
            [
                'name',
                'type',
                '_id'
            ]
        )
    }
)
require "httparty"
require "json"

token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token 
    "filter" : JSON.dump({
            :name => 'docs',
            :type => 'service'
        }),
        'fields': JSON.dump({
            [
                'name',
                'type',
                '_id'
            ]
        })
    }
}
response = HTTParty.get('https://api.serverdensity.io/inventory/resources', params)

response.to_json

<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$filter = array(
    "name" => "docs",
    "type" => "service"
);
$fields = array("name", "type", "_id");
$client->api('services')->search($filter, $fields);

?>

# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

filter = {
  'name':'Llama',
  'type': 'service'
}

fields = ['name', 'type', '_id']

token = '2dfae5bf81f65492a40569d39b29ffa3'
agent_key = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
service = client.services.search(filter, fields=fields)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "51f6585e11f144673749afbb",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "currentStatus": "up",
        "body": [],
        "name": "Llama",
        "slowThreshold": 500,
        "timeout": 10,
        "checkType": "HTTP",
        "checkUrl": "http://example.org",
        "checkMethod": "GET",
        "checkLocations": [
            "dub"
        ],
        "notes": "",
        "group": null,
        "type": "service",
        "updatedAt": "2016-02-31T13:59:34",
        "createdAt": "2016-02-31T13:59:34",
        "deleted": false, 
        "headers": [], 
        "validateCert": false,
        "tags": null,
    }
]

Query Params

token
string
required

Your API token.

filter
string
required

A JSON encoded hash of the fields that you wish to search by. Any field returned can be searched on.

fields
string

A JSON encoded array of the fields that you wish returned by the call.

 
Suggest Edits

Updating a service

 
puthttps://api.serverdensity.io//inventory/services/serviceId
curl -v -X PUT https://api.serverdensity.io/inventory/services/51f932d0dba4bbf15d001219?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=Changed+Llama
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
service_id = '51f7ecd4dba4bbee5d000a74'

api_response = requests.put(
    'https://api.serverdensity.io/inventory/services/{0}'.format(service_id),
    params={'token': token},
    data={"name": "Changed Llama"}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
service_id = '51f7ecd4dba4bbee5d000a74'

params = {
    :query => {"token" => token},
    :body => {"name": "Changed Llama"}
}

response = HTTParty.put("https://api.serverdensity.io/inventory/services/#{service_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = "76oeu57a5765a76e5a7";

$fields = array(
    "name" => "Changed llama",
);
$fields = array("name", "type", "_id");
$client->api('services')->search($id, $fields);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
data={"name": "Changed Llama"}

client = ApiClient(token)
service = client.services.update(data=data)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "Changed Llama",
    "updatedAt": "2016-02-31T16:25:22",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "_id": "51f932d0dba4bbf15d001219"
}

Path Params

serviceId
string
required

The ID of your service.

Body Params

token
string
required

Your API token.

name
string

The display name for the service.

checkType
string

The type of check: either http or tcp

timeout
int32

How many seconds to wait until timing out. Max 30.

checkLocations
string

A JSON list of locations to check from e.g. ["lon", "dub"]. Each location has its own "API ID" which is noted on the locations list.

group
string

The group the service belongs to.

checkUrl
string

HTTP Check - The URL to issue the request to.

checkMethod
string

HTTP Check - The HTTP method used to issue the check: either GET or POST.

slowThreshold
int32

HTTP Check - Request time millisecond threshold after which service is deemed slow.

body
string

HTTP Check - Content of the HTTP request body

host
string

TCP Check - The hostname or IP address to issue the TCP check to

port
string

TCP Check - The port number to issue the TCP check to

data
string

TCP Check - The content to send when opening the TCP socket

validateCert
boolean

Whether to validate the SSL certificate or not

auth
string

Basic HTTP auth username and password. e.g. {"username":"Thomas", "password":"password"}

headers
string

HTTP headers to include e.g. {"User-Agent": "Thomas the Tank Engine"}

tags
string

A JSON list of tag IDs.

 
Suggest Edits

View service by ID

 
gethttps://api.serverdensity.io//inventory/services/serviceId
curl -v -X GET https://api.serverdensity.io/inventory/services/51f91846dba4bbf05d001335/?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

service_id = '51f6585e11f144673749afbb'

api_response = requests.get(
    'https://api.serverdensity.io/inventory/services/{0}'.format(service_id),
    params = {'token': 'b97da80a41c4f61bff05975ee51eb1aa'}
)

require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
service_id = "22ddab237dff5cde07dc70a26e93c262"

params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/services/#{service_id}", params)

response.to_json

<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = "76oeu57a5765a76e5a7";

$client->api('services')->view($id);

?>

# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
service_id = '51f6585e11f144673749afbb'

client = ApiClient(token)
service = client.services.view(service_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f6585e11f144673749afbb",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "currentStatus": "up",
    "body": [],
    "name": "Llama",
    "slowThreshold": 500,
    "timeout": 10,
    "checkType": "HTTP",
    "checkUrl": "http://example.org",
    "checkMethod": "GET",
    "checkLocations": [
        "dub"
    ],
    "notes": "",
    "group": null,
    "type": "service",
    "updatedAt": "2016-02-31T13:59:34",
    "createdAt": "2016-02-31T13:59:34",
    "deleted": false, 
    "headers": [], 
    "validateCert": false,
    "tags": null,
}

Path Params

serviceId
string
required

The ID of your service.

Query Params

token
string
required

Your API token.

 
Suggest Edits

Listing service groups

 
gethttps://api.serverdensity.io//inventory/services/groups/?token=token
curl -X GET https://api.serverdensity.io/inventory/services/groups/?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"

r = requests.get(
    'https://api.serverdensity.io/inventory/services/groups',
    params = {
        'token': token 
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/services/groups", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('services')->serviceGroups();

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    "Group1", 
    "Group2", 
    "Group3"
]

Path Params

token
string
required

Your API token

 
Suggest Edits

View service errors

 
gethttps://api.serverdensity.io//service-monitor/errors/serviceId/
# Return all errors for service ID 520dee51cbda5de279000013
curl -v -X GET https://api.serverdensity.io/service-monitor/errors/520dee51cbda5de279000013/?token=b97da80a41c4f61bff05975ee51eb1aa

# Return last error for service ID 520dee51cbda5de279000013
curl -v -X GET https://api.serverdensity.io/service-monitor/errors/520dee51cbda5de279000013/?token=b97da80a41c4f61bff05975ee51eb1aa&resultPerPage=1

# Return all errors from China location for service ID 520dee51cbda5de279000013
curl -v -X GET https://api.serverdensity.io/service-monitor/errors/5829e91d95fe3584618b456c/?token=b97da80a41c4f61bff05975ee51eb1aa&location=sha-cvh

import requests

service_id = '51f932d0dba4bbf15d001219'

api_response = requests.get(
    'https://api.serverdensity.io/service-monitor/errors/%s' % service_id,
    params={
	'token':'b97da80a41c4f61bff05975ee51eb1aa',
        'start':'2016-11-25T12:35:41Z',
        'end':'2016-12-02T12:35:41Z',
        'filter' :'{"code":200,"location_name":"sha-cvh","error":{"$regex":"received"}}'
    },

)

require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
service_id = "22ddab237dff5cde07dc70a26e93c262"

params = {
	:query => {
		"token" => token,
    	'filter' => JSON.dump()

	}
}

response = HTTParty.get("https://api.serverdensity.io/service-monitor/errors/#{service_id}", params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
 "_id": "51f932d0dba4bbf15d001219",
 "accountId": "521fab2365fe354273u000000",
 "barium": "6add8031-075r-44q3-b7af-f22de68a08e4",
 "code": 200,
 "createdAt": "2016-12-01T06:03:04Z",
 "error": "Operation timed out after 10000 milliseconds with 0 bytes received",
 "location": "exm-a2.sha.cvh",
 "location_name": "sha-cvh",
 "serviceId": "51f932d0dba4bbf15d001219"
    }
]

Path Params

serviceId
string
required

The id of your service

Query Params

start
string

The date you want to begin the error query.

end
string

The date you want to end the query

filter
string

Used to find errors based on their Error Message, Location, or Status Code.

token
string
required

API token required to access confidential information

 

Filter options

code - This filter option will search and return all errors with a match of your desired status code in the error description.
location_name - This filter option will search and return all errors from the specified monitoring location.
error - This filter option will search and return all errors with the specified error message in the error description.

Suggest Edits

Creating an alert

Create new alerts on devices or services, at an item or group level.

 
posthttps://api.serverdensity.io//alerts/v3/configs
curl -i -X POST "https://api.serverdensity.io/alerts/v3/configs/?token=806e9c7fiu6bd4a4cf089d1469065b8" \
	-d metric=system.disk.free \
	-d tags='{"device_name": {"type": "eq", "value": "/dev"}}' \
	-d scope='{"type": "device", "value": "5a4e2768b03e85fw348b456b"}' \
	-d comparison=gte \
	-d value=50 \
	-d fix=1 \
	-d recipients='[{"type":"user","id":"58299fa39a35bb742b8b45b2","actions":["sms","email"]}]' 
import json
import requests

token = '8dacb989734647c8c5bbf81713f8442b'
headers = {'Content-Type': 'application/json'}
payload = {
        'metric': 'system.disk.free',
        'section': 'system',
        'comparison': 'gte',
        'enabled': True,
        'value': 50,
        'recipients': 
            [],
        'wait':
            {
                "seconds": 60,
                "enabled": True,
                "displayUnits": "s"
            },
        'repeat':
            {
                "seconds": 300,
                "enabled": True,
                "displayUnits": "s"
            },
        'scope':
        	{
        		"type": "device", "value": "5a4e2768b33e85ff248b456b"
        	},
        'tags':
        	{
        		"device_name": {"type": "eq", "value": "/dev"}
        	},

        'fix': '1'
    }

api_response = requests.post('https://api.serverdensity.io/alerts/v3/configs',
    params={'token': token},
    data=json.dumps(payload),
    headers=headers
)

print api_response.text, api_response
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token},
    :body => {
      	'metric' => 'system.disk.free',
        'comparison' => 'gte',
        'value' => 0,
        'recipients' => JSON.dump(
            [{
                "type" => "user",
                "id" =>"520dec7ecbda5d317300000a",
                "actions" => [
                    "sms",
                    "email"
                ]
            }]
        ),
        'wait' => JSON.dump(
            {
                "seconds" => 60,
                "enabled" => true,
                "displayUnits" => "s"
            }
        ),
      	'scope' => JSON.dump(
            {
                "device" => "578590fyua35bb8c318b456a",
            }
        ),
      	'tags' => JSON.dump(
            {
                "device_name" => "/",
            }
        ),
        'repeat' => JSON.dump(
            {
                "seconds" => 300,
                "enabled" => true,
                "displayUnits" => "s"
            }
        ),
        'fix' => true
    }
}

response = HTTParty.post("https://api.serverdensity.io/alerts/v3/configs", params)

response.to_json

<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);
$alert = array(
    'subjectId' => '520dee51cbda5de279000013',
    'subjectType' => 'device',
    'section' => 'system',
    'field' => 'loadAvrg',
    'comparison' => 'gte',
    'value' => 0
);
$recipients = array(
    "type" => "user",
    "id" =>"520dec7ecbda5d317300000a",
    "actions" => [
        "sms",
        "email"
    ]
);
$wait = array(
    "seconds" => 60,
    "enabled" => true,
    "displayUnits" => "s"
);
$repeat = array(
    "seconds" => 300,
    "enabled" => true,
    "displayUnits" => "s"
);


$client->api('alerts')->create($alert, $recipients, $wait, $repeat);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

data={
    'subjectId': '520dee51cbda5de279000013',
    'subjectType': 'device',
    'section': 'system',
    'field': 'loadAvrg',
    'comparison': 'gte',
    'value': 0,
    'recipients': 
    [{
        "type": "user",
        "id":"520dec7ecbda5d317300000a",
        "actions": [
          "sms",
          "email"
        ]
      }],
    'wait':
    {
      "seconds": 60,
      "enabled": 'true',
      "displayUnits": "s"
    },
    'repeat':
    {
      "seconds": 300,
      "enabled": 'true',
      "displayUnits": "s"
    },
    'fix': 'True'
  }

client = ApiClient(token)
device = client.alerts.create(data=data)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Date: Thu, 13 Jul 2017 10:19:11 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: __cfduid=dd142a18e92f0bea41b86ac6438b999901499865150; expires=Fri, 13-Jul-18 10:19:10 GMT; path=/; domain=.serverdensity.io; HttpOnly
Access-Control-Expose-Headers: X-Barium, X-First-Page, X-Last-Page, X-Next-Page, X-Previous-Page, X-Snapshot-Current, X-Snapshot-Next, X-Snapshot-Previous, X-Total-Closed, X-Total-Error, X-Total-Filter, X-Total-Number, X-Total-Open, X-User-Closed, X-User-Open, X-Plugins-Truncated, X-Plugins-Counts, Location
Location: /configs/5943691fec18a84674031632/
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: DELETE, GET, OPTIONS, POST, PUT
Server: cloudflare-nginx
CF-RAY: 37dbr7a05a36tab5-LHR

Body Params

token
string
required

Your API token

enabled
boolean

Whether the alert is enabled or not. Shown as pause/resume in the web UI.

comparison
string
required

The comparison type for the alert. See table below for full list of comparisons.

value
string
required

The value to trigger the alert based on the comparison

recipients
string

JSON encoded list of objects describing recipients and actions (see below)

wait
string

JSON encoded object describing the amount of time to wait before first alert notification (see below)

repeat
string

JSON encoded object describing how often to repeat the alert notifications (see below)

fix
boolean

Whether the alert is fixed or not.

metric
string
required

Metric identifier e.g. "system.disk.free"

tags
array

The set of tags to match against. The type can be either "eq" for an exact match or "re" for RegEx. Tags should not be set if the metric has no associated tags. You can check for metric tags by querying the metric metadata

aggregatorTagOperator
string

The operator to use to match the values of several payloads. Accepts "count". Used for Service alerts only.

aggregatorTagValue
int32

The value to check against for tag query. The value will be the amount of locations configured for the Service alert. Used in Service alerts only.

aggregatorTagComparison
string

Supports "gte". Used in Service alerts only.

scope
object
required

Scope holds the devices or services that will be checked against the alert and has the format {"type": <type>, "value": <id>} where <type> can be device, service or deviceGroup, serviceGroup and <id> is the unique identifier for <type>

 

Comparisons

Comparison Explanation
lt less than
gt greater than
lte less than or equal to
gte greater than or equal to
eq equal to
neq not equal to
c contains
nc does not contain
re matches regex
nre does not match regex
ex does exist
nex does not exist

Parameters: Recipients

Parameters Required Type Description
type Yes string The type of recipient: user, pagerduty or webhook
id Yes string The ID of the recipient e.g. user ID or webhook ID
actions depends string The notification types to send, not required for pagerduty, webhook, slack or hipchat types

You can list all of your recipients with the List Recipients endpoint. You can also Create Recipients too. If you're using a webhook recipient you might want to familiarise yourself with the webhook payload format

Parameters: Wait

Parameters Required Type Description
seconds Yes string The number of seconds to wait.
enabled Yes string Whether the wait configuration is enabled or not
displayUnits Yes string Hint for the UI, always s (may change in future releases)

Parameters: Repeat

Parameters Required Type Description
seconds Yes string The number of seconds to wait.
enabled Yes string Whether the wait configuration is enabled or not
displayUnits Yes string Hint for the UI, always s (may change in future releases)
Suggest Edits

Deleting an alert

 
deletehttps://api.serverdensity.io//alerts/v3/configs/alertId
curl -v -X DELETE https://api.serverdensity.io/alerts/v3/configs/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

delete_response = requests.delete(
    "https://api.serverdensity.io/alerts/v3/configs/{0}".format(alert_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
alert_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/alerts/v3/configs/#{alert_id}", 
    params
)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = "id here";

$client->api('alerts')->delete($id);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
alert_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
device = client.alerts.delete(alert_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 204 No Content
Date: Wed, 05 Jul 2017 16:32:50 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Set-Cookie: __cfduid=de5eedca31defbf209e8c7e3cd2296ea51499272369; expires=Thu, 05-Jul-18 16:32:49 GMT; path=/; domain=.serverdensity.io; HttpOnly
Access-Control-Expose-Headers: X-Barium, X-First-Page, X-Last-Page, X-Next-Page, X-Previous-Page, X-Snapshot-Current, X-Snapshot-Next, X-Snapshot-Previous, X-Total-Closed, X-Total-Error, X-Total-Filter, X-Total-Number, X-Total-Open, X-User-Closed, X-User-Open, X-Plugins-Truncated, X-Plugins-Counts, Location
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: DELETE, GET, OPTIONS, POST, PUT
Server: cloudflare-nginx
CF-RAY: 379bb8f51b243376-LHR

Path Params

alertId
string
required

The ID of the alert to be deleted

Body Params

token
string
required

Your API token

 
Suggest Edits

Listing all alerts

Get a list of all configured alerts on your account.

 
gethttps://api.serverdensity.io//alerts/v3/configs
curl -v -X GET https://api.serverdensity.io/alerts/v3/configs/?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

requests.get(
    'https://api.serverdensity.io/alerts/configs',
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
        'filter': json.dumps({
            'field':'loadAvrg',
        })
    }
)
require "httparty"

token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token,
    "filter" => JSON.dump({
            "field" => "loadAvrg"
        })
}
response = HTTParty.get('https://api.serverdensity.io/alerts/configs', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('alerts')->all();

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "5203a041dba4bb6010000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "comparison": "gt",
        "createdAt": {
            "sec": 1375969345,
            "usec": 0
        },
        "deleted": false,
        "enabled": true,
        "field": "loadAvrg",
        "fix": true,
        "fullField": "system-loadAvrg",
        "group": "",
        "locationThreshold": 1,
        "lastTriggeredAt": {
            "sec": 1418210271,
            "usec": 578000
        },
        "notificationSent": true, 

        "recipients": [
            {
                "id": "52037dd6dba4bbc014000349",
                "type": "user",
                "actions": [
                    "email"
                ]
            },
            {
                "id": "52037dd6dba4bb391e00009e",
                "type": "user",
                "actions": [
                    "email"
                ]
            }
        ],
        "repeat": {
            "seconds": 0,
            "enabled": false,
            "displayUnits": "s"
        },
        "open": true,
        "section": "system",
        "subject": null,
        "subjectId": "52037df285ce7525c4f5813a",
        "subjectType": "device",
        "updatedAt": {
            "sec": 1375969354,
            "usec": 0
        },
        "valid": true,
        "value": "2",
        "wait": {
            "seconds": 0,
            "enabled": false,
            "displayUnits": "s"
        },
        "waitTriggered": false
    }
]

Query Params

token
string
required

Your API token.

filter
string

A JSON encoded hash of the fields that you wish to search by. Any field returned can be searched on.

 
Suggest Edits

Listing alerts by ID

 
gethttps://api.serverdensity.io//alerts/v3/configs/alertId
curl -i -X GET "https://api.serverdensity.io/alerts/v3/configs/5059e60a5d2o3e7d84u37bcf?token=b97da80a41c4f61bff05975ee51eb1aa"
import requests

alert_id = '5059e60a5d2o3e7d84u37bcf'

requests.get(
    'https://api.serverdensity.io/alerts/v3/configs/{0}'.format(alert_id),
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
    }
)
require "httparty"

token = 'b97da80a41c4f61bff05975ee51eb1aa'
subject_id = '5059e60a5d2o3e7d84u37bcf'

params = {:query => {
    "token" => token 
    "subjectType": "device"
}
response = HTTParty.get('https://api.serverdensity.io/alerts/v3/configs/#{subject_id}', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = '5059e60a5d2o3e7d84u37bcf';
$type = 'device'

$client->api('alerts')->bySubject($id, $type);

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "scope": {
    "device": "5925i6f3oa35ib8c3i8bi56a"
  },
  "updatedAt": "2017-06-29T12:14:02Z",
  "tags": {
    "device_name": "\/"
  },
  "_id": "5059e60a5d2o3e7d84u37bcf",
  "metric": "system.disk.free",
  "accountId": "58299fa395fe35a9368b45ba",
  "comparison": "gte",
  "createdAt": "2017-06-29T12:14:02Z",
  "value": "50",
  "recipients": [
    {
      "id": "502997a39a357b74258b45b2",
      "actions": [
        "sms",
        "email"
      ],
      "type": "user"
    }
  ],
  "valid": true,
  "version": "v3",
  "fix": true
}

Path Params

alertId
string
required

The ID of the alert

Query Params

token
string
required

Your API token.

 
Suggest Edits

Updating alerts

Update existing alerts on devices or services, at an item or group level.

 
puthttps://api.serverdensity.io//alerts/v3/configs/alertId
#Full update:
curl -i -X PUT "https://api.serverdensity.io/alerts/v3/configs/596757523d18a84a380e3633?token=806e9c7fiu6bd4a4cf089d1469065b8" \
	-d metric=system.disk.free \
	-d tags='{"device_name": "/"}' \
	-d scope='{"type": "device", "value": "5a4e276e403e85fe048b456b"}' \
	-d comparison=gte \
	-d value=50 \
	-d fix=1 \
	-d recipients='[{"type":"user","id":"58299fa39a35bb742b8b45b2","actions":["sms","email"]}]'
  
#Partial update:
curl -i -X PATCH "https://api.serverdensity.io/alerts/v3/configs/596757523d18a84a380e3633?token=834f9c81ff86bsd24cf029d146e06dd8" -d metric=system.disk.woop
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

api_response = requests.patch(
    'https://api.serverdensity.io/alerts/v3/configs/{0}'.format(alert_id),
    params={'token': token},
    data={
        "value": 5,
        "recipients": json.dumps(
            [{
                "type":"user",
                "id":"520dec7ecbda5d317300000a",
                "actions": ["email"]
            }]
        )
    }
)
require "httparty"
require 'json'

token = "b97da80a41c4f61bff05975ee51eb1aa"
alert_id = '51f7ecd4dba4bbee5d000a74'

params = {
    :query => {"token" => token},
    :body => {
        "value" => 5,
        "recipients" => JSON.dump(
            [{
                "type" =>"user",
                "id" =>"520dec7ecbda5d317300000a",
                "actions" => ["email"]
            }]
        )
    }        
}

response = HTTParty.patch(
    "https://api.serverdensity.io/alerts/v3/configs/#{alert_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$fields = array(
       "value" => 5,
);

$arrayFields = array(
   $recipients => array(
   "type" => "user",
   "id" =>"520dec7ecbda5d317300000a",
   "actions" => [
       "sms",
       "email"
   ]
)
);

$id = '65oae4a65oe46a5oe4ao';
$type = 'device';

$client->api('alerts')->update($id, $fields, $arrayFields);

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 204 No Content
Date: Thu, 13 Jul 2017 11:41:55 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Set-Cookie: __cfduid=d37c7fb5a60ddfb33320d9f42f7d69eb81492156115; expires=Fri, 13-Jul-18 11:41:55 GMT; path=/; domain=.serverdensity.io; HttpOnly
Access-Control-Expose-Headers: X-Barium, X-First-Page, X-Last-Page, X-Next-Page, X-Previous-Page, X-Snapshot-Current, X-Snapshot-Next, X-Snapshot-Previous, X-Total-Closed, X-Total-Error, X-Total-Filter, X-Total-Number, X-Total-Open, X-User-Closed, X-User-Open, X-Plugins-Truncated, X-Plugins-Counts, Location
Location: /configs/59345756eqw2a84a38031633/
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: DELETE, GET, OPTIONS, POST, PUT
Server: cloudflare-nginx
CF-RAY: 37dbf9d33cd50b81-LHR

Path Params

alertId
string
required

The ID of the service to update

Body Params

token
string
required

Your API token.

enabled
boolean

Whether the alert is enabled or not. Shown as pause/resume in the web UI

comparison
string
required

The comparison type for the alert. See table below for full list of comparisons.

value
string
required

The value to trigger the alert based on the comparison

recipients
string

JSON encoded list of objects describing recipients and actions (see below)

wait
string

JSON encoded object describing the amount of time to wait before first alert notification (see below)

repeat
string

JSON encoded object describing how often to repeat the alert notifications (see below)

group
string

The group the alert should be created on

metric
string
required

Metric identifier e.g. "system.disk.free"

tags
array

The set of tags to match against.

aggregatorTagOperator
string

The operator to use to match the values of several payloads. Accepts "count". Used for Service alerts only.

aggregatorTagValue
int32

The value to check against for tag query. The value will be the amount of locations configured for the Service alert. Used in Service alerts only.

aggregatorTagComparison
string

Supports "gte". Used in Service alerts only.

scope
object
required

Scope holds the devices or services that will be checked against the alert and has the format {"type": <type>, "value": <id>} where <type> can be device, service or deviceGroup, serviceGroup and <id> is the unique identifier for <type>

 

Comparisons

Comparison Explanation
lt less than
gt greater than
lte less than or equal to
gte greater than or equal to
eq equal to
neq not equal toc - contains
nc does not contain
re matches regex
nre does not match regex

Parameters: Recipients

Parameters Required Type Description
type Yes string The type of recipient: user, pagerduty or webhook
id Yes string The ID of the recipient e.g. user ID or webhook ID
actions depends string The notification types to send, not required for pagerduty or webhook types`

Parameters: Wait

Parameters Required Type Description
seconds Yes string The number of seconds to wait.
enabled Yes string Whether the wait configuration is enabled or not
displayUnits Yes string Hint for the UI, always s (may change in future releases)

Parameters: Repeat

Parameters Required Type Description
seconds Yes string The number of seconds to wait.
enabled Yes string Whether the wait configuration is enabled or not
displayUnits Yes string Hint for the UI, always s (may change in future releases)
Suggest Edits

Viewing alerts by device/service ID

 
gethttps://api.serverdensity.io//alerts/v3/configs/
curl -v -X GET 'https://api.serverdensity.io/alerts/v3/configs/?token=8dacb989701327c8c5awe21713f8442b&filter={"scope":{"type":"device","value":"5a843f6fb13e8553558b456a"}}'
import requests
import json


item_id = '5a84qw6fb34e85535565456a'
item_type = 'device'
token = '8dads989701644d8c5aaf8177if89i2b'

filter = {"scope":{"type": item_type ,"value": item_id}}

api_response = requests.get(
    'https://api.serverdensity.io/alerts/v3/configs/',
    params={'token': token,
        'filter': json.dumps(filter)
        }
)
print api_response.text
require "httparty"

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

params = {:query => {
    "token" => token 
}
response = HTTParty.get('https://api.serverdensity.io/alerts/v3/configs/#{alert_id}', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = "76oeu57a5765a76e5a7";

$client->api('alerts')->view($id);

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
  {
    "subject": null,
    "section": "system",
    "waitTriggeredAt": "2017-11-03T11:45:45Z",
    "fix": true,
    "_id": "59fc53facbeff40694bddcc0",
    "version": "v3",
    "lastTriggeredAt": "2017-11-13T17:16:56Z",
    "open": true,
    "subjectType": "device",
    "wait": {
      "enabled": true,
      "seconds": 300,
      "displayUnits": "s"
    },
    "comparison": "c",
    "fullField": "system-Process-processNotRunning",
    "field": "processNotRunning",
    "enabled": true,
    "scope": {
      "type": "device",
      "value": "59fc53f9b13e85860a8b456b"
    },
    "repeat": {
      "enabled": false,
      "seconds": 0,
      "displayUnits": "s"
    },
    "subjectId": "59fc53f9b13e85860a8b456b",
    "metric": "serverdensity.processes.running",
    "accountId": "59fc518335bfc29a038b4572",
    "createdAt": "2017-11-03T11:33:14Z",
    "updatedAt": "2017-11-03T11:39:55Z",
    "aggregatorTagComparison": "gte",
    "waitTriggered": true,
    "recipients": [
      {
        "type": "user",
        "actions": [
          "email"
        ],
        "id": "59fc518435bfc29a038b4573"
      }
    ],
    "valid": true,
    "value": "\/usr\/sbin\/cron",
    "aggregatorTagValue": 1,
    "aggregatorTagOperator": "count"
  }

Path Params

alertId
string
required

The ID of the alert to view

Query Params

token
string
required

Your API token.

 
Suggest Edits

Pausing & resuming alerts

Pausing and resuming existing alerts on devices or services, at an item or group level.

 
patchhttps://api.serverdensity.io//alerts/v3/configs/alertId
curl -v -X PATCH https://api.serverdensity.io/alerts/v3/configs/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data enabled=false
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

api_response = requests.patch(
    'https://api.serverdensity.io/alerts/v3/configs/{0}'.format(alert_id),
    params={'token': token},
    data={"enabled": False}
)
require "httparty"
require 'json'

token = "b97da80a41c4f61bff05975ee51eb1aa"
alert_id = '51f7ecd4dba4bbee5d000a74'

params = {
    :query => {"token" => token},
    :body => {
        "enabled" => false 
    }        
}

response = HTTParty.patch(
    "https://api.serverdensity.io/alerts/v3/configs/#{alert_id}", params)

response.to_json

<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$fields = array(
    "enabled" => false,
);

$id = '65oae4a65oe46a5oe4ao';

$client->api('alerts')->update($id, $fields);

?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "subjectId": "520dee51cbda5de279000013",
    "subjectType": "device",
    "section": "system",
    "field": "loadAvrg",
    "comparison": "gte",
    "value": "0",
    "recipients": [
        {
            "type": "user",
            "id": "520dec7ecbda5d317300000a",
            "actions": [
                "sms",
                "email"
            ]
        }
    ],
    "wait": {
        "seconds": 60,
        "enabled": true,
        "displayUnits": "s"
    },
    "repeat": {
        "seconds": 300,
        "enabled": true,
        "displayUnits": "s"
    },
    "fix": true,
    "enabled": true,
    "subject": null,
    "valid": true,
    "accountId": "4fa3c6ef22257d6c2f000000",
    "createdAt": {
        "sec": 1379244529,
        "usec": 0
    },
    "updatedAt": {
        "sec": 1379244529,
        "usec": 0
    },
    "_id": "523599f19711f423690003e4"
}

Path Params

alertId
string
required

The ID of the alert to update

Body Params

token
string
required

Your API token.

enabled
string
required

Whether the alert is enabled or not. false = paused, true = enabled.

 
Suggest Edits

Triggered alerts

Get a list of all triggered alerts on your account, per subject (device or service) or per alert config.

 
gethttps://api.serverdensity.io//alerts/triggered
# Return all triggered alerts
curl -v -X GET https://api.serverdensity.io/alerts/triggered?token=b97da80a41c4f61bff05975ee51eb1aa

#Return all open triggered alerts
curl -v -X GET https://api.serverdensity.io/alerts/triggered?closed=false&token=b97da80a41c4f61bff05975ee51eb1aa

# Return all closed triggered alerts
curl -v -X GET "https://api.serverdensity.io/alerts/triggered?closed=true&token=b97da80a41c4f61bff05975ee51eb1aa"

# Return all open triggered alerts for device 520dee51cbda5de279000013
curl -v -X GET "https://api.serverdensity.io/alerts/triggered/?subjectType=device&token=b97da80a41c4f61bff05975ee51eb1aa&filter='{"config.subjectId":"520dee51cbda5de279000013"}'"

# Return all open triggered alerts for serviceGroup websites
curl -v -X GET "https://api.serverdensity.io/alerts/triggered/?subjectType=serviceGroup&token=b97da80a41c4f61bff05975ee51eb1aa&filter='{"config.subjectId":"websites"}'"

# Return all open triggered alerts on the account with the device name and ID
curl -v -X GET "https://api.serverdensity.io/alerts/triggered?closed=true&includeNames=true&token=866e9c81ff86bd4a4cf029d146e065b8"
import requests
# Return all triggered alerts

requests.get(
    'https://api.serverdensity.io/alerts/triggered',
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'}
)
import requests
# Return all open triggered alerts

requests.get(
    'https://api.serverdensity.io/alerts/triggered',
    params={
        'closed': 'false',
        'token': 'b97da80a41c4f61bff05975ee51eb1aa'
    }
)
import requests
# Return all closed triggered alerts

requests.get(
    'https://api.serverdensity.io/alerts/triggered',
    params={
        'closed': 'true',
        'token': 'b97da80a41c4f61bff05975ee51eb1aa'
    }
)
import requests
# Return all open triggered alerts for device 520dee51cbda5de279000013

requests.get(
    'https://api.serverdensity.io/alerts/triggered/',
    params={
        'subjectType': 'device',
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
        'filter': json.dumps({
            'config.subjectId':'520dee51cbda5de279000013',
        		'fixed':'false'
        })

    }
)
# Return all triggered alerts

require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token 
}
response = HTTParty.get('https://api.serverdensity.io/alerts/triggered', params)

response.to_json
# Return all open triggered alerts

require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token,
    "closed" => false 
}
response = HTTParty.get('https://api.serverdensity.io/alerts/triggered', params)

response.to_json
# Return all closed triggered alerts

require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token,
    "closed" => true 
}
response = HTTParty.get('https://api.serverdensity.io/alerts/triggered', params)

response.to_json
# Return all open triggered alerts for device 520dee51cbda5de279000013

require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'
device_id = "520dee51cbda5de279000013"

params = {:query => {
        'subjectType' => 'device',
        'token' => token,
        'filter': JSON.dump({
            :config.subjectId => 'device_id',
          	:fixed => 'false'
        })
}
response = HTTParty.get('https://api.serverdensity.io/alerts/triggered/', params)

response.to_json
<?php
# Return all triggered alerts
$client->api('alerts')->triggered()

?>
<?php
# Return all open triggered alerts
$device_id = "520dee51cbda5de279000013";

$client->api('alerts')->triggered($closed=false)
# Return all closed triggered alerts
?>
<?php
# Return all closed triggered alerts
$device_id = "520dee51cbda5de279000013";

$client->api('alerts')->triggered($closed=true)
# Return all open triggered alerts for device 520dee51cbda5de279000013
?>
<?php
# Return all open triggered alerts for device 520dee51cbda5de279000013

$client->api('alerts')->triggered($closed=false, 'device', '520dee51cbda5de279000013')

?>

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "5232f915ab8b69c63429028b",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "config": {
            "subjectType": "device",
            "fullField": "system-loadAvrg",
            "open": true,
            "createdAt": {
                "sec": 1379072212,
                "usec": 0
            },
            "subject": null,
            "group": "",
            "fix": true,
            "subjectId": "520dee51cbda5de279000013",
            "field": "loadAvrg",
            "valid": true,
            "accountId": "4fa3c6ef22257d6c2f000000",
            "lastTriggeredAt": {
                "sec": 1379080968,
                "usec": 0
            },
            "repeat": {
                "seconds": 60,
                "enabled": true,
                "displayUnits": "s"
            },
            "recipients": [
                {
                    "type": "user",
                    "id": "520dec7ecbda5d317300000a",
                    "actions": [
                        "email"
                    ]
                }
            ],
            "deleted": false,
            "updatedAt": {
                "sec": 1379072229,
                "usec": 0
            },
            "wait": {
                "seconds": 0,
                "enabled": false,
                "displayUnits": "s"
            },
            "comparison": "gte",
            "enabled": true,
            "value": "0",
            "_id": "5232f8d42ea0b7d131000000",
            "section": "system"
        },
        "firstTriggeredAt": {
            "sec": 1379072277,
            "usec": 0
        },
        "fixed": false,
        "triggeredAt": [
            {
                "sec": 1379072277,
                "usec": 0
            },
            {
                "sec": 1379072278,
                "usec": 0
            }
        ],
        "updatedAt": {
            "sec": 1379081031,
            "usec": 0
        }
    }
]

Query Params

token
string
required

Your API token.

closed
string

Whether to filter by closed or open alerts - unset = all alerts, false = open alerts, true = closed alerts.

subjectType
string

The type of the subject - device, service, deviceGroup or serviceGroup if you also specify the subjectId as part of the URL (see examples below)

filter
string

You can provide a JSON encoded hash filter for the search that will return items that match the filter. The filter can include anything that is available on the triggered data, or the config that the triggered data contains.

includeNames
boolean

If enabled, the request will return the device ID and name for each alert.

 

Additional Headers

This endpoint also returns the following headers:

X-Total-Closed:
X-Total-Filter:
X-Total-Open:
X-User-Closed:
X-User-Id:
X-User-Open:

Filter Options

Some filter options are not present in the returned data or the config:
limit - Use this to limit the total results returned, defaults to 100
dateFrom - Use this to limit the returned triggered alerts by date.
You can filter on any of the config options in a similar fashion to below.
config.subjectId - Use this to limit by subjectId (including group names).
config.subjectType - Use this to limit by subject type
config.field - Use this to filter by field, e.g loadAvrg

Example Filter

{"limit":10,"dateFrom":"2016-06-20T15:45:57+00:00","fixed":true, "config.subjectId":"websites", "config.subjectType":"deviceGroup", "config.field":"loadAvrg"}

Suggest Edits

Listing device alert metrics

Devices and services have different alert metrics which you can configure in the ui. The section correspond to the top-level of the alert metric whereas field corresponds to the subsection of the given section.

 
gethttps://api.serverdensity.io//alerts/device_alerts.json
curl -v -X GET https://api.serverdensity.io/alerts/device_alerts.json?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"

devices = requests.get(
    'https://api.serverdensity.io/alerts/device_alerts.json',
    params={'token': token}
)

require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {
    :query => {"token" => token} 
}

devices = HTTParty.get(
    "https://api.serverdensity.io/alerts/device_alerts.json", params)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "mongoDB": {
        "metrics": {
            "aIx": {
                "units": "/s",
                "fullName": "MongoDB Index accesses",
                "name": "Index accesses",
                "excludeComparisons": ["c", "nc", "re", "nre"],
                "formatDecimals": 0
            },
            "vMem": {
                "units": "MB",
                "fullName": "MongoDB Memory - virtual",
                "name": "Memory - virtual",
                "excludeComparisons": ["c", "nc", "re", "nre"],
                "formatDecimals": 0
            }
        }
    },
  	...
    "noData": {
        "metrics": {
            "device": {
                "noComparisons": true,
                "fullName": "No data received from device",
                "noValue": true,
                "name": "From Device"
            }
        },
        "name": "No Data"
    }
}

Query Params

token
string
required

Your API token

 
Suggest Edits

Listing service alert metrics

Devices and services have different alert metrics which you can configure in the ui. The section correspond to the top-level of the alert metric whereas field corresponds to the subsection of the given section.

 
gethttps://api.serverdensity.io//alerts/service_alerts.json
curl -v -X GET https://api.serverdensity.io/alerts/service_alerts.json?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"

services = requests.get(
    'https://api.serverdensity.io/alerts/service_alerts.json',
    params={'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {
    :query => {"token" => token} 
}

services = HTTParty.get(
    "https://api.serverdensity.io/alerts/device_alerts.json", params
)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "http": {
        "metrics": {
            "status": {
                "fullName": "Status",
                "availableChoices": ["down", "slow", "up"],
                "name": "Status",
                "excludeComparisons": ["lt", "gt", "lte", "gte", "c", "nc", "re", "nre"]
            },
           ...
            "time": {
                "units": "s",
                "fullName": "HTTP Response time",
                "name": "Response time",
                "excludeComparisons": ["c", "nc", "nre", "re", "eq", "neq"],
                "formatDecimals": 0
            }
        },
        "type": "service",
        "name": "HTTP"
    },
    "tcp": {
        "metrics": {
            "status": {
                "fullName": "Status",
                "availableChoices": ["down", "slow", "up"],
                "name": "Status",
                "excludeComparisons": ["lt", "gt", "lte", "gte", "c", "nc", "re", "nre"]
            }
        },
        "type": "service",
        "name": "TCP"
    }
}

Query Params

token
string
required

Your API token

 
Suggest Edits

Listing recipients

Get a list of non-user recipients for alerts including Slack, HipChat, PagerDuty and WebHooks

 
gethttps://api.serverdensity.io//notifications/recipients/
curl -v -X GET "https://api.serverdensity.io/notifications/recipients?token=b97da80a41c4f61bff05975ee51eb1aa"
import requests

api_response = requests.get(
    'https://api.serverdensity.io/notifications/recipients',
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
    }
)
require "httparty"

token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
    "token" => token,
}
response = HTTParty.get('https://api.serverdensity.io/notifications/recipients', params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No response examples available

Query Params

token
string
required

Your API token

 
Suggest Edits

Creating a recipient

Create recipients for your alert notifications

 
posthttps://api.serverdensity.io//notifications/recipients
curl -v -X POST https://api.serverdensity.io/notifications/recipients/?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=OpsChannel \
     --data token=520dee51cbda5de279000013 \
     --data type=slack \
     --data channel=#ops
import json
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

api_response = requests.post(
    'https://api.serverdensity.io/notifications/recipients',
    params={'token': token},
    data={
        'name': 'OpsChannel',
        'token': '520dee51cbda5de279000013',
        'type': 'slack',
        'channel': '#ops'
   }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token},
    :body => {
        'name' => 'OpsChannel',
        'token' => '520dee51cbda5de279000013',
        'type' => 'slack',
        'channel' => '#ops'
    }
}

response = HTTParty.post("https://api.serverdensity.io/notifications/recipients", params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No response examples available

Body Params

token
string

Your integration API token

name
string
required

The name of your notification integration

type
string
required

The type of notification integration

channel
string

Channel name for chat integrations

url
string

URL for webhook integrations

 

If you're using a webhook recipient you might want to familiarise yourself with the webhook payload format

Suggest Edits

Deleting recipients

 
deletehttps://api.serverdensity.io//notifications/recipients/id
curl -v -X DELETE https://api.serverdensity.io/notifications/recipients/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa
token = 'b97da80a41c4f61bff05975ee51eb1aa'
recipient_id = '523599f19711f423690003e4'

delete_response = requests.delete(
    "https://api.serverdensity.io/notifications/recipients/{0}".format(recipient_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
recipient_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/notifications/recipients/#{recipient_id}", 
    params
)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "523599f19711f423690003e4"
}

Path Params

id
string
required

the ID of the recipient you wish to delete

Query Params

token
string
required

Your API token

 
Suggest Edits

Listing costs

Get the alerts history items limited by the given filter. If configId filter is set, then the results contains all events for that alert configuration. In any other case, the results are aggregated by itemId and configId including the following derived values:

  • duration the sum of event durations.
  • triggeredCount the number of events for that alert in that item.
  • cost the HumanOps cost in seconds. For more information please check our support docs

When the query is aggregated, the non-derived fields are from the document whose startDate is the newest. In addition to this, an unique id is generated by concatenating the itemId and the configId.

 
gethttps://api.serverdensity.io//alerts/history/
curl -v -X GET "https://api.serverdensity.io/alerts/history/?start=2016-05-21T10:11:03Z&end=2016-06-20T10:11:03Z&token=b97da80a41c4f61bff05975ee51eb1aa"
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

r = requests.get(
    'https://api.serverdensity.io/alerts/history,
    params={
    	'token': token,
        'start' : '2016-03-10T12:35:07Z',
        'end': '2016-03-10T15:35:07Z'
    		}
)
require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'

params = {:query => {
        'start' => '2016-03-10T12:35:07Z',
        'end' => '2016-03-10T15:35:07Z',
        'token' => token
}
response = HTTParty.get('https://api.serverdensity.io/alerts/history/', params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "56d03b584321dc2a01da335856e06862056e2660f6912543",
        "accountId": "4fa3c6ef22257d6c2f004354",
        "config": {
            "_id": "56e06862056e2660f6987638",
            "comparison": "neq",
            "field": "code",
            "fullField": "http-code",
            "recipients": [
                {
                    "actions": [
                        "email"
                    ],
                    "id": "56cc8a5fd4d274f91e334b28",
                    "type": "user"
                }
            ],
            "section": "http",
            "subject": null,
            "value": 10
        },
        "cost": 488,
        "duration" : 143,
        "endDate": "2016-03-03T15:16:21Z",
        "endValue": 8,
        "fixed": false,
        "itemId": "56d03b581942dc2a01da9954",
        "peak": 51.27,
        "startDate": "2016-03-03T12:53:01Z",
        "startValue": 15,
        "triggeredCount": 15
    },
    {
    ...
    }
]

Query Params

token
string
required

Your API token

start
string
required

A string in the format, the beginning of the time frame eg. 2016-03-10T12:35:07Z

end
string
required

A string in the format, the end of the time frame eg. 2016-03-10T15:35:07Z

fields
string

json encoded string - An array or a dict with all the fields we want returned

filter
string

json encoded string - A dict with the filters we want to apply to the query (ex: {"config.field":"code"}). The allowed filters are: config.section, config.field, config.fullField,

sort
string

Field to sort by. Allowed values: itemName, config.fullField, fixed, duration, peak, startDate, cost, triggeredCount

order
string

Sort ordering: ascending, descending

page
int32

Page number, default = 1

perPage
int32

Documents that we're going to get per page. Default = 20

configId
string

_id of the config you want to limit by

 
Suggest Edits

Viewing costs

Get the alerts history items limited by the given filter and the itemId. If configId filter is set, then the results contains all events for that alert configuration. In any other case, the results are aggregated by itemId and configId including the following derived values:

  • duration the sum of event durations.
  • triggeredCount the number of events for that alert in that item.
  • cost the HumanOps cost in seconds. For more information please check our support docs

When the query is aggregated, the non-derived fields are from the document whose startDate is the newest. In addition to this, an unique id is generated by concatenating the itemId and the configId.

 
gethttps://api.serverdensity.io//alerts/history/itemId
curl -v -X GET "https://api.serverdensity.io/alerts/history/56d03b581942dc2a01da9954/?start=2016-05-21T10:11:03Z&end=2016-06-20T10:11:03Z&token=b97da80a41c4f61bff05975ee51eb1aa"
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
item_id = '56d03b581942dc2a01da9954'

r = requests.get(
    'https://api.serverdensity.io/alerts/history/{0}'.format(item_id),
    params={
    	'token': token,
        'start' : '2016-03-10T12:35:07Z',
        'end': '2016-03-10T15:35:07Z'
    		}
)
require "httparty"

token = 'b97da80a41c4f61bff05975ee51eb1aa'
item_id = '56d03b581942dc2a01da9954'

params = {:query => {
        'start' => '2016-03-10T12:35:07Z',
        'end' => '2016-03-10T15:35:07Z',
        'token' => token
}

response = HTTParty.get('https://api.serverdensity.io/alerts/history/#{item_id}', params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "56d03b584321dc2a01da335856e06862056e2660f6912543",
        "accountId": "4fa3c6ef22257d6c2f004354",
        "config": {
            "_id": "56e06862056e2660f6987638",
            "comparison": "neq",
            "field": "code",
            "fullField": "http-code",
            "recipients": [
                {
                    "actions": [
                        "email"
                    ],
                    "id": "56cc8a5fd4d274f91e334b28",
                    "type": "user"
                }
            ],
            "section": "http",
            "subject": null,
            "value": 10
        },
        "cost": 488,
        "duration" : 143,
        "endDate": "2016-03-03T15:16:21Z",
        "endValue": 8,
        "fixed": false,
        "itemId": "56d03b581942dc2a01da9954",
        "peak": 51.27,
        "startDate": "2016-03-03T12:53:01Z",
        "startValue": 15,
        "triggeredCount": 15
    },
    {
    ...
    }
]

Path Params

itemId
string
required

The ID of a device or service

Query Params

token
string
required

Your API token

start
string
required

A string in the format, the beginning of the time frame eg. 2016-03-10T12:35:07Z

end
string
required

A string in the format, the end of the time frame eg. 2016-03-10T15:35:07Z

fields
string

json encoded string - An array or a dict with all the fields we want returned

filter
string

json encoded string - A dict with the filters we want to apply to the query (ex: {"config.field":"code"}). The allowed filters are: config.section, config.field, config.fullField

sort
string

Field to sort by. Allowed values: itemName, config.fullField, fixed, duration, peak, startDate, cost, triggeredCount

order
string

Sort ordering: ascending, descending

page
int32

Page number, default = 1

perPage
int32

Documents that we're going to get per page. Default = 20

configId
string

_id of the config you want to limit by

 
Suggest Edits

Available Metrics

Determine which metrics are available to return historical data for. Metrics can be returned for the whole account, a specific item (device or service), or the scope can be narrowed using a filter.

 
gethttps://api.serverdensity.io//metrics/v3/metrics
// Metrics meta for an account
curl -v -X GET "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa"

// Get metadata for a single metric
curl -v -X GET "https://api.serverdensity.io/metrics/v3/metrics/apache.net.bytes?token=b97da80a41c4f61bff05975ee51eb1aa"

// Metrics meta from an inventoryfilter
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode filter='{"scope":[{"filter":"web*"}]}'

// Metrics meta from an item id
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode  filter='{"scope": [{"item": "5a79e996b03e85b1378b456f"}]}'

// Metrics meta from a group of item ids 
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode filter='{"scope": [{"group": ["5a79e996b03e85b1378b456f", "5a79e996b03e85b1378b456d"]}]}'

// Metrics meta from a deviceGroup
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=8dacb989701647c8c5aaf81713f8442b" \
    --data-urlencode filter='{"scope": [{"deviceGroup": "devices"}]}'
   
// Metrics meta from a serviceGroup
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode filter='{"scope": [{"serviceGroup": "services"}]}'

// Metrics meta from a inventory filter and a item
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode filter='{"scope": [{"filter": "hcluster.*"},{"item": "5916bce22ee0b5069393d941"}]}'

// Only certain metrics meta from an item
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode filter='{"scope": [{"item": "5916bce22ee0b5069393d941"}],"metrics": [{"type": "eq", "value": "system.io.wait"},{"type": "eq", "value": "system.net.bytes_sent"}]}'

// Metrics meta for two items using regex
curl -i -G "https://api.serverdensity.io/metrics/v3/metrics/?token=b97da80a41c4f61bff05975ee51eb1aa" \
    --data-urlencode filter='{"scope": [{"item": "5916bce22ee0b5069393d941"},{"item": "5916bce22ee0b5069393d942"}],"metrics": [{"type": "re", "value": ".used$"},{"type": "eq", "value": "system.net.bytes_sent"}]}'

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "apache.net.bytes": {
        "description": "",
        "numericType": "gauge",
        "perUnit": "",
        "plugin": "apache",
        "shortName": "",
        "tags": [],
        "type": "int",
        "unit": ""
    },
    "apache.net.bytes_per_s": {
        "description": "",
        "numericType": "gauge",
        "perUnit": "",
        "plugin": "apache",
        "shortName": "",
        "tags": [],
        "type": "int",
        "unit": ""
    },
    "apache.net.hits": {
        "description": "",
        "numericType": "gauge",
        "perUnit": "",
        "plugin": "apache",
        "shortName": "",
        "tags": [],
        "type": "int",
        "unit": ""
    },
...
}

Query Params

token
string
required

Your API token

filter
object

A filter to allow only specific metadata to be returned.

filter.scope
array of objects
filter.metrics
array of objects
 

Scope

You can define the scope of the query using the scope list in your filter. It has the format type: id where type is one of the following

Type
Description
Example

item

The ObjectId string which uniquely identifies the item

{"item": "5a79e996b03e85b1378b456f"}

group

A list of item identifiers

{"group": ["5a79e996b03e85b1378b456f", "5a79e996b03e85b1378b456d"]}

filter

A list of search terms, searching the inventory

{"filter":"web*"}

serviceGroup

A service group name string

{"serviceGroup": "services"}

deviceGroup

a device group name string

{"deviceGroup": "devices"}

Metrics

You can further define the scope by specifying the metrics to be returned in your filter. Metrics can be searched by exact match, or by regex. This has the format {'type': 'eq|re', 'value': 'val'} with eq meaning exact match and re meaning regex.

Examples are provided above.

Suggest Edits

Get metrics

Returns historical metrics data, for a specific subject (device or service) over a specific time range.

 
gethttps://api.serverdensity.io//metrics/v3/query/
# Return system.io.wait metric for all devices on the account.

curl "https://api.serverdensity.io/metrics/v3/query/?token=766e9c81f86bd94a4c0029d146e065b8" -d requests='[{"metric":"system.io.wait","aggregation":"avg"}]' -d start=2017-07-23T16:15:00Z

# Return system.io.wait metric for a single device

curl "https://api.serverdensity.io/metrics/v3/query/?token=766e9c81f86bd94a4c0029d146e065b8" -d requests='[{"metric":"system.io.wait","scope":[{"item":"55b6c79495fe35354e123456"}]}]' -d start=2017-07-23T16:15:00Z

# Return system.io.wait metric for two devices

curl "https://api.serverdensity.io/metrics/v3/query/?token=766e9c81f86bd94a4c0029d146e065b8" -d requests='[{"metric":"system.io.wait","scope":[{"items":["55b6c79495fe35354e123456", "55b6c79495fe35354e125456"]}]},{"metric":"system.net.bytes_rcvd"}]' -d start=2018-03-15T04:45:00Z 

# Return serverdensity.cpu.idle metrics tagged with device_name:CPU0 for a device

curl "https://api.serverdensity.io/metrics/v3/query/?token=766e9c81f86bd94a4c0029d146e065b8" -d requests='[{"metric":"serverdensity.cpu.idle","scope":[{"item":"55b6c79495fe35354e123456"}],"tags":{"device_name":"CPU0"}}]' -d start=2018-04-18T12:38:08Z 




# Return system.io.wait metric for all devices on the account.

import json 
from datetime import datetime, timedelta 

import requests

subject_id = '523599f19711f423690003e4' 
token = '866e9c8143862d4afwc022d236e065b8'

# get start and end date via datetime 
start = datetime.now() - timedelta(seconds=3600) 

api_response = requests.get( 
'https://api.serverdensity.io/metrics/v3/query/?token={0}'.format(token), 
params={ 
'requests': '[{"metric":"system.","aggregation":"avg"}]', 
'start' : start.strftime('%Y-%m-%dT%H:%I:%SZ'), 
} 
)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "series": [
    {
      "start": 1500826500,
      "itemId": "596f7c85919e351d638b196b",
      "end": 1501075364,
      "metric": "system.io.wait",
      "tags": {
        
      },
      "interval": 60,
      "pointlist": [
        
      ]
    },
    {
      "start": 1500826500,
      "itemId": "59719d829a35bb019f8b4567",
      "end": 1501075364,
      "metric": "system.io.wait",
      "tags": {
        
      },
      "interval": 60,
      "pointlist": [
        
      ]
    },
    {
      "start": 1500826500,
      "itemId": "519684819a35bbac29194569",
      "end": 1501075364,
      "metric": "system.io.wait",
      "tags": {
        
      },
      "interval": 60,
      "pointlist": [
        
      ]
    }
  ]
}

Query Params

token
string
required

Your API token

start
string
required

The UTC date string for the start time range in format YYYY-MM-DDTHH:mm:SSZ e.g. 2013-09-15T00:00:00Z

end
string

The UTC date string for the end time range in format YYYY-MM-DDTHH:mm:SSZ e.g. 2013-09-15T23:59:59Z

Body Params

requests
array of objects

An object with queries - metric(string), tags(dict), scope(list), aggregation(string)

 

Note that data is stored in a particular retention policy which will return minute and hourly data points depending on the time range. If the query ranges over 1 day, hourly data points will be returned, otherwise you will get a data point for every minute. The 1 minute data points are only stored for the last 5 days.

Suggest Edits

Dynamic metrics

Return historical metrics data, for a devices and/or services that match a search or regex style inventory filter search over a specific time range.

 
gethttps://api.serverdensity.io//metrics/dynamicgraphs/
# Filter by network traffic, eth0, received MB/s
# Only return metrics for devices that match the pattern (.*)cloud

curl -v -X GET https://api.serverdensity.io/metrics/dynamicgraphs/?token=b97da80a41c4f61bff05975ee51eb1aa\&inventoryFilter=*cloud\&start=2016-01-25T16:51:56Z\&end=2016-01-27T16:51:56Z\&filter='\{"networkTraffic":\{"eth0":\["rxMByteS"\]\}\}'
# Filter by network traffic, eth0, received MB/s

import json
from datetime import datetime, timedelta

import requests

subject_id = '523599f19711f423690003e4'
inventoryFilter = '.*cloud'

# get start and end date via datetime
start = datetime.now() - timedelta(seconds=600)
end = datetime.now()

# build a filter
# eth0 rxMBytesS
filter = {
    'networkTraffic': {
        'eth0': ['rxMByteS']
    }
}

api_response = requests.get(
    'https://api.serverdensity.io/metrics/dynamicgraphs/{0}'.format(inventoryFilter),
    params={
        'token': token,
        'start' : start.isoformat(),
        'end': end.isoformat(),
        'filter': json.dumps(filter)
    }
)
require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'
inventoryFilter = '*.cloud'

params = {:query => {
        'start' => '2013-09-15T17:00:00Z',
        'end' => '2013-09-15T18:00:00Z',
        'token' => token,
        'filter' => JSON.dump({
            'networkTraffic' => {
                'eth0' => ['rxMByteS']
            }
        })
}
response = HTTParty.get('https://api.serverdensity.io/metrics/dynamicgraphs/#{inventoryFilter}', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$inventoryFilter = "*.cloud";

$filter = array('networkTraffic' => [
        'eth0' => ['rxMByteS']
    ]
);

$client->api('metrics')->dynamicMetrics($inventoryFilter, $filter, time()-7200, time());
?>
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "name": "Network traffic",
        "key": "networkTraffic",
        "tree": [
            {
                "name": "eth0",
                "tree": [
                    {
                        "name": "Received MBs",
                        "unit": false,
                        "data": [
                            {
                                "x": 1379268526,
                                "y": 0.001953125
                            },
                            {
                                "x": 1379268585,
                                "y": 0.0034505208333333
                            },
                            {
                                "x": 1379268645,
                                "y": 0.0017903645833333
                            },
                            {
                                "x": 1379268709,
                                "y": 0.0018880208333333
                            },
                            {
                                "x": 1379268769,
                                "y": 0.00166015625
                            },
                        ]
                    }
                ]
            }
        ]
    }
]

Query Params

token
string
required

Your API token

inventoryFilter
string

A regular expression that will return all devices or services that match the pattern.

ids
string

List of inventory IDs

names
string

Human-readable names of a device or service

start
string
required

The UTC date string for the start time range in format YYYY-MM-DDTHH:mm:SSZ e.g. 2013-09-15T00:00:00Z

end
string
required

The UTC date string for the end time range in format YYYY-MM-DDTHH:mm:SSZ e.g. 2013-09-15T23:59:59Z

type
string

Specify whether to return only devices, services or all.

 
Suggest Edits

Overall status (meta)

Get the overall status for a service check.

 
gethttps://api.serverdensity.io//service-monitor/meta/serviceId
curl -v -X GET https://api.serverdensity.io/service-monitor/meta/5241a3cbdba4bbb8100002a1/?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
service_id = '5241a3cbdba4bbb8100002a1'

api_response = requests.get(
    'https://api.serverdensity.io/service-monitor/meta/{0}'.format(service_id),
    params={'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
service_id = '5241a3cbdba4bbb8100002a1'

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/service-monitor/meta/#{service_id}', params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
service_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
status = client.service_status.overall(service_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "currentStatus": "up",
  "metrics": {
    "status": 1.0,
    "time": 0.30260759999999987
  },
  "serviceId": "5241a3cbdba4bbb8100002a1",
  "createdAt": "2016-02-24T14:38:03",
  "updatedAt": "2016-02-24T16:06:57.639000"
}

Path Params

serviceId
string
required

the ID of the service to retrieve the details for.

Query Params

token
string
required

Your API token.

 
Suggest Edits

Location service status (last)

Get the current results from a service check.

 
gethttps://api.serverdensity.io//service-monitor/last/serviceId
curl -v -X GET https://api.serverdensity.io/service-monitor/last/5241a3cbdba4bbb8100002a1/?token=b97da80a41c4f61bff05975ee51eb1aa

import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
service_id = '5241a3cbdba4bbb8100002a1'

api_response = requests.get(
    'https://api.serverdensity.io/service-monitor/last/{0}'.format(service_id),
    params={'token': token}
)

require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
service_id = '5241a3cbdba4bbb8100002a1'

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/service-monitor/last/#{service_id}', params)

response.to_json

# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
service_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
locations = client.service_status.location(service_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "_id": "5241a65b8dd13a0eb6b9bf88",
    "_rtt": 3.254435,
    "accountId": "4fa3c6ef22257d6c2f000000",
    "code": 200,
    "content": "92c6852fd45a084b4c04ec7232d7b092",
    "createdAt": "2016-02-24T14:48:56.627000",
    "error": null,
    "headers": {
      "Connection": "close",
      "Content-Encoding": "gzip",
      "Content-Length": "3970",
      "Content-Type": "text/html; charset=UTF-8",
      "Date": "Wed, 24 Feb 2016 14:49:00 GMT",
      "Server": "Apache",
      "Set-Cookie": "landing=CM8n9FJXla01e91pbzepdThtUhjYRg6XlMCfT6P0k4-BewzH6xWQmtwOrBrH0LSf7p-4hM1GMSoXmtT52PgUVxZ96GMgnznj2-v5SHv_fuY.; expires=Wed, 24-Sep-2014 14:49:00 GMT; path=/",
      "Vary": "Accept-Encoding",
      "X-Ua-Compatible": "IE=edge,chrome=1"
    },
    "location": "man-34s",
    "location_node": "localhost",
    "service": {},
    "serviceId": "5241a3cbdba4bbb8100002a1",
    "status": "up",
    "success": true,
    "time": 0.293897,
    "type": "http",
    "updatedAt": "2016-02-24T14:48:59.881000"
  },
]

Path Params

serviceId
string
required

The ID of the service to retrieve the details for.

Query Params

token
string
required

Your API token.

 
Suggest Edits

Creating a user

 
posthttps://api.serverdensity.io//users/users
curl -v -X POST https://api.serverdensity.io/users/users/?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data admin=false \
     --data firstName=Llama \
     --data lastName=Hat \
     --data login=llama \
     --data password=biu687ftg \
     --data emailAddresses='["hello@serverdensity.com"]' \
     --data phoneNumbers='["+16464194674"]'
import json
import requests

api_response = requests.post(
    'https://api.serverdensity.io/users/users',
    params={'token': token},
    data={
        'admin': False,
        'firstName': 'Llama',
        'lastName': 'Hat',
        'login': 'llama',
        'password': 'biu687ftg',
        'emailAddresses': json.dumps(['hello@serverdensity.com']),
        'phoneNumbers': json.dumps(['+16464194674']),
        'permissions': json.dumps({
                "tags": {"548984f976d377a53d459be4": {
                    "mode": "read"
                }}
            })
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token},
    :body => {
        'admin' => false,
        'firstName' => 'Llama',
        'lastName' => 'Hat',
        'login' => 'llama',
        'password' => 'biu687ftg',
        'emailAddresses' => JSON.dump(['hello@serverdensity.com']),
        'phoneNumbers' => JSON.dump(['+16464194674']),
        'permissions': JSON.dump({
        "tags" => {"548984f976d377a53d459be4" => {
            "mode" => "read"}}
        })
    }
}

response = HTTParty.post("http://api.serverdensity.io/users/users", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$user = array(
    'admin' => false,
    'firstName' => 'Llama',
    'lastName' => 'Hat',
    'login' => 'llama',
    'password' => 'biu687ftg',
    'emailAddresses' => ['hello@serverdensity.com'],
    'phoneNumbers' => ['+16464194674'],
);

$client->api('users')->create($user, ['my', 'tags']);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
data={
  'admin': False,
  'firstName': 'Llama',
  'lastName': 'Hat',
  'login': 'llama',
  'password': 'biu687ftg',
  'emailAddresses': ['hello@serverdensity.com'],
  'phoneNumbers': ['+16464194674'],
  'permissions': {
      "tags": {"548984f976d377a53d459be4": {
          "mode": "read"
        }}
    }
}

client = ApiClient(token)
user = client.users.create(data)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "admin": false,
    "firstName": "Llama",
    "lastName": "Hat",
    "login": "llama",
    "emailAddresses": [
        "hello@serverdensity.com"
    ],
    "phoneNumbers": [
        " 16464194674"
    ],
    "gravatar": "http://www.gravatar.com/avatar/abc013bd0be76d8d25656c3ab7bd1fa2",
    "updatedAt": "2016-02-05T13:43:17",
    "createdAt": "2016-02-05T13:43:17",
    "_id": "5278f5f576d3774043000000",
    "permissions": {
        "tags": {"548984f976d377a53d459be4": {
            "mode": "read"
        }}
    }
}

Body Params

token
string
required

Your API token.

admin
string
required

Admin user or not.

firstName
string
required

User first name.

lastName
string
required

User last name.

login
string
required

Username for login

password
string
required

Password for login

emailAddresses
string
required

JSON list of e-mail addresses.

phoneNumbers
string
required

JSON list of phone numbers in international format with country code.

permissions
string

A dictionary that contains the key tags, tags itself is a dictionary that contains the tag IDs. Each tag ID is a dictionary with a key mode and value read

 
Suggest Edits

Deleting a user

 
deletehttps://api.serverdensity.io//users/users/userId
curl -v -X DELETE https://api.serverdensity.io/users/users/5278f5f576d3774043000000?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
user_id = '5278f5f576d3774043000000'

delete_response = requests.delete(
    "https://api.serverdensity.io/users/users/{0}".format(user_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
user_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/users/users/#{user_id}", 
    params
)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = '32465e65a65eu6a5465aoe';

$client->api('users')->delete($id, ['my', 'tags']);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
_id = '2dfae5bf81f65492a40569d39b29ffa5'


client = ApiClient(token)
user_id = client.users.delete(_id)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "5278f5f576d3774043000000"
}

Path Params

userId
string
required

The ID of the user to delete

Body Params

token
string
required

Your API token.

 
Suggest Edits

Listing all users

Get a list of every user on your account.

 
gethttps://api.serverdensity.io//users/users
curl -v -X GET https://api.serverdensity.io/users/users?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

requests.get(
    'https://api.serverdensity.io/users/users',
    params = {'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/users/users', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('users')->all();

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
users = client.users.list()
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "5278f5f576d3774043000000",
        "admin": false,
        "createdAt": "2016-02-05T13:43:17",
        "emailAddresses": [
            "hello@serverdensity.com"
        ],
        "firstName": "Llama",
        "gravatar": "http://www.gravatar.com/avatar/abc013bd0be76d8d25656c3ab7bd1fa2",
        "lastName": "Hat",
        "login": "llama",
        "phoneNumbers": [
            " 16464194674"
        ],
        "updatedAt": "2016-02-05T13:43:17",
        "permissions": {
            "tags": {"548984f976d377a53d459be4": {
                "mode": "read"
            }}
        }
    }
]

Query Params

token
string
required

Your API token

 
Suggest Edits

Updating a user

 
puthttps://api.serverdensity.io//users/users/userId
curl -v -X PUT https://api.serverdensity.io/users/users/5278f5f576d3774043000000?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data firstName=James
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
user_id = '5278f5f576d3774043000000'

api_response = requests.put(
    'https://api.serverdensity.io/users/users/{0}'.format(user_id),
    params={'token': token},
    data={"firstName": "James"}
)
require "httparty"
require 'json'

token = "b97da80a41c4f61bff05975ee51eb1aa"
user_id = '5278f5f576d3774043000000'

params = {
    :query => {"token" => token},
    :body => {
        "firstName" => "James"
    }        
}

response = HTTParty.put(
    "https://api.serverdensity.io/users/users/#{user_id}", params)

response.to_json

<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$user = array(
    'name' => 'Changed llama'
);
$id = 'e6o5a65oe6e5o6ae4a';
$client->api('users')->update($id, $user);

?>

# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
user_id = '5278f5f576d3774043000000'

data={"firstName": "James"}

client = ApiClient(token)
user = client.users.update(user_id, data)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "firstName": "James",
    "updatedAt": "2016-02-05T13:53:51",
    "_id": "5278f5f576d3774043000000"
}

Path Params

userId
string
required

ID of the user you're updating

Body Params

token
string
required

Your API token

 
Suggest Edits

Viewing a user

 
gethttps://api.serverdensity.io//users/users/userId
curl -v -X GET https://api.serverdensity.io/users/users/5278f5f576d3774043000000?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

user_id = '5278f5f576d3774043000000'

api_response = requests.get(
    'https://api.serverdensity.io/users/users/{0}'.format(user_id),
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
user_id = '5278f5f576d3774043000000'

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/users/users/#{user_id}', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = 'e6o5a65oe6e5o6ae4a';
$client->api('users')->view($id);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
user_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
user = client.users.view(user_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "5278f5f576d3774043000000",
    "admin": false,
    "createdAt": "2016-02-05T13:43:17",
    "emailAddresses": [
        "hello@serverdensity.com"
    ],
    "firstName": "Llama",
    "gravatar": "http://www.gravatar.com/avatar/abc013bd0be76d8d25656c3ab7bd1fa2",
    "lastName": "Hat",
    "login": "llama",
    "phoneNumbers": [
        " 16464194674"
    ],
    "updatedAt": "2016-02-05T13:43:17",
    "permissions": {
        "tags": {"548984f976d377a53d459be4": {
            "mode": "read"
        }}
    }
}

Path Params

userId
string
required

Your API token

Query Params

token
string
required

ID of the user you want to view

 
Suggest Edits

Creating a postback

You can use this method to post data back to Server Density without using the agent, for example using your own scripts or to integrate in something custom you are doing. You will still be restricted to posting back once per minute using this method, as you would be using the agent.

 
posthttps://api.serverdensity.io//alerts/postbacks/
# Send system.load.1, my.custom.metric & my.custom.metric.count as gauge metrics with the tag key:value

curl -X POST "https://api.serverdensity.io/alerts/postbacks?token=b97da80a41c4f61bff05975ee51eb1aa" \
   --data hash=12442a69ad6629a5942d56c126d3205b \
   --data payload='{"agentKey":"23ddab267dff7cde05dc20a28e93c272","agentVersion": "2.0", "sdAgentVersion": 2.0, "metrics":[["system.load.1",1526312932,8,{"hostname":"example.com","type":"gauge","tags":["key:value"]}],["my.custom.metric",1526312932,1,{"hostname":"example.com","type":"gauge","tags":["key:value"]}],["my.custom.metric.count",1526312932,2,{"hostname":"example.com","type":"gauge","tags":["key:value"]}]]}' \
   --header "X-Forwarded-Host: YOURACCOUNT.serverdensity.io"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
OK
{
    "message":"bad_request",
    "errors":
        [
            {
                "type":"hash_mismatch",
                "message":"Unable to process payload due to mismatch in hash"
            }
        ]
    }

Body Params

token
string
required

Your API token

payload
string
required

The payload you want to post back to us. Must contain the agentKey for the device to send the data to.

hash
string
required

An md5 hash of the JSON encoded payload, used for error checking.

X-Forwarded-Host
string
required

Set this to your Server Density account url, e.g. example.serverdensity.io

 
Suggest Edits

Creating a new dashboard

 
posthttps://api.serverdensity.io//users/dashboards
curl -v -X POST https://api.serverdensity.io/users/dashboards/?token=b97da80a41c4f61bff05975ee51eb1aa \
  --data name=dashname
import json
import requests

api_response = requests.post(
    'https://api.serverdensity.io/users/dashboards',
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa'
    },
    data={
        'name': 'dashname',
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {
    :query => {"token" => token},
    :body => {
      "name" => "dashname"
    }
}

response = HTTParty.post("https://api.serverdensity.io/users/dashboards", params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

data = {
  'name': 'dashname',
}

client = ApiClient(token)
dashboard = client.dashboards.create(data)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "name":"dashname",
  "accountId":"4fa3c6ef22257d6c2f000000",
  "_id":"545742cfd4d3680e0a3348a9"
}

Body Params

token
string
required

Your API token

name
string
required

Name of the dashboard.

layout
string

Dictionary with the ids of the widgets from this dashboard as keys. The values are objects with 3 values: col (column), row (row), size_x (size in the x axis, from 1 to 6)

 
Suggest Edits

Deleting a dashboard

 
deletehttps://api.serverdensity.io//users/dashboards/dashboardId
curl -v -X DELETE https://api.serverdensity.io/users/dashboards/5278f5f576d3774043000000?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
dashboard_id = '5278f5f576d3774043000000'

delete_response = requests.delete(
    "https://api.serverdensity.io/users/dashboards/{0}".format(dashboard_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
dashboard_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/users/dashboards/#{dashboard_id}", 
    params
)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
dashboard_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
_id = client.dashboards.delete(dashboard_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "5278f5f576d3774043000000"
}

Path Params

dashboardId
string
required

ID of the dashboard to delete

Body Params

token
string
required

Your API token

 
Suggest Edits

List all dashboards

 
gethttps://api.serverdensity.io//users/dashboards
curl -v -X GET https://api.serverdensity.io/users/dashboards?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

requests.get(
    'https://api.serverdensity.io/users/dashboards',
    params = {'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/users/dashboards', params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
device = client.dashboards.list()


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "_id": "532c054495fe352d6d84b9e7",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "layout": {
      "5451159395fe35d3055f60df": {
        "col": 1,
        "row": 1,
        "size_x": 6
      }
    },
    "name": "dash",
    "timeRange": {
      "from": "2016-03-21T08:24:18Z",
      "to": "2016-03-21T09:24:18Z",
      "timePreset": {
        "key": "1 hour ago"
      }
    }
  },
  {
    "_id": "5457a1fad998d12f038b4567",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "layout": {
      "5457a1ff95fe35c63174751f": {
        "col": 1,
        "row": 1,
        "size_x": 2
      }
    },
    "name": "dash2"
  }
]

Query Params

token
string
required

Your API token

 
Suggest Edits

Updating a dashboard

 
puthttps://api.serverdensity.io//users/dashboards/dashboardId
curl -v -X PUT https://api.serverdensity.io/users/dashboards/54525649d4d368e620334887?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=mynewdashboard2
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
dashboard_id = '5278f5f576d3774043000000'

api_response = requests.put(
    'https://api.serverdensity.io/users/dashboards/{0}'.format(dashboard_id),
    params={'token': token},
    data={"name": "mynewdashboard2"}
)
require "httparty"
require 'json'

token = "b97da80a41c4f61bff05975ee51eb1aa"
dashboard_id = '5278f5f576d3774043000000'

params = {
    :query => {"token" => token},
    :body => {
        "name" => "mynewdashboard2"
    }        
}

response = HTTParty.put(
    "https://api.serverdensity.io/users/dashboards/#{dashboard_id}", params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
dashboard_id = '22ddab237dff5cde07dc70a26e93c262'
data={"name": "mynewdashboard2"}

client = ApiClient(token)
dashboard = client.dashboards.update(dashboard_id, data)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "name": "mynewdashboard2",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "_id": "54525649d4d368e620334887"
}

Path Params

dashboardId
string
required

The ID of the dashboard to update.

Body Params

token
string
required

Your API token

name
string

Name of the dashboard.

layout
string

Dictionary with the ids of the widgets from this dashboard as keys. The values are objects with 3 values: col (column), row (row), size_x (size in the x axis, from 1 to 6)

 
Suggest Edits

Viewing a dashboard

 
gethttps://api.serverdensity.io//users/dashboards/dashboardId
curl -v -X GET https://api.serverdensity.io/users/dashboards/5278f5f576d3774043000000?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

dashboard_id = '5278f5f576d3774043000000'

api_response = requests.get(
    'https://api.serverdensity.io/users/users/{0}'.format(dashboard_id),
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
dashboard_id = '5278f5f576d3774043000000'

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/users/users/#{dashboard_id}', params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
dashboard_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
dashboard = client.dashboards.view(dashboard_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_id": "532c054495fe352d6d84b9e7",
  "accountId": "4fa3c6ef22257d6c2f000000",
  "layout": {
    "5451159395fe35d3055f60df": {
      "col": 1,
      "row": 1,
      "size_x": 6
    }
  },
  "name": "dash",
  "timeRange": {
    "from": "2016-03-21T08:24:18Z",
    "to": "2016-03-21T09:24:18Z",
    "timePreset": {
      "key": "1 hour ago"
    }
  }
}

Path Params

dashboardId
string
required

ID of the dashboard to view

Query Params

token
string
required

Your API token

 
Suggest Edits

Duplicating a dashboard

 
posthttps://api.serverdensity.io//users/dashboards/duplicate/:dasboardId
curl -X POST https://api.serverdensity.io/users/dashboards/duplicate/54525649d4d368e620334887?token=b97da80a41c4f61bff05975ee51eb1aa&new_name=dashname
import json
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
dashboard_id = '5278f5f576d3774043000000'

api_response = requests.post(
    'https://api.serverdensity.io/users/dashboards/duplicate/{0}'.format(dashboard_id),
    params={
        'token': token,
        'new_name': 'New dash name'
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
dashboard_id = '5278f5f576d3774043000000'

params = {
    :query => {
        "token" => token,
        "name" => "dashname"
    }
}

response = HTTParty.post("https://api.serverdensity.io/users/dashboards/duplicate/#{dashboard_id}", params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "5678223e056e260fc72c2de4",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "addedAutomatically": true,
    "global": false,
    "layout": {
        "5678223e056e260fc72c2de5": {
            "col": 2,
            "row": 1,
            "size_x": 2,
            "size_y": 1
        },
        "5678223e056e260fc72c2de6": {
            "col": 1,
            "row": 1,
            "size_x": 1,
            "size_y": 1
        },
        "5678223e056e260fc72c2de7": {
            "col": 4,
            "row": 1,
            "size_x": 2,
            "size_y": 1
        }
    },
    "name": "William's first dashboard-copy",
    "owner": "5678211ed4d3688207334873"
}

Body Params

token
string
required

Your API token

dashboardId
string
required

ID of the dashboard to duplicate

new_name
string

Name of the new, duplicated dashboard

 
Suggest Edits

Creating a widget

 
posthttps://api.serverdensity.io//users/v3/widgets
curl -v -X POST https://api.serverdensity.io/users/v3/l,widgets/?token=b97da80a41c4f61bff05975ee51eb1aa \
  --data type=graph \
  --data dashboardId=5457a1fad998d12f038b4567
import json
import requests

api_response = requests.post(
    'https://api.serverdensity.io/users/widgets',
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa'
    },
    json={
        'type': 'elasticGraph',
        'dashboardId': '5457a1fad998d12f038b4567'
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {
    :query => {"token" => token},
    :body => {
      "type" => "elasticGraph",
      "dashboardId" => "5457a1fad998d12f038b4567"
    }
}

response = HTTParty.post("https://api.serverdensity.io/users/widgets", params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

data = {
  'type': 'elasticGraph',
  'dashboardId': '5457a1fad998d12f038b4567'
}

client = ApiClient(token)
widget = client.widgets.create(data)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_id": "5457b3b495fe35d54d747520",
  "type": "elasticGraph",
  "dashboardId": "5457a1fad998d12f038b4567",
  "accountId": "4fa3c6ef22257d6c2f000000"
}

Body Params

token
string
required

Your API token

dashboardId
string
required

ID of the dashboard this widget belongs to

type
string
required

Type of widget - see table below for allowed values

config
string
required

Configuration of widget. See the full details below to learn how to configure a widget

 

Types of Widget

Widget Description
cloudStatus Status of some cloud vendors
graph Graph widget with time series data
openAlerts Open alerts from the selected device/service/group
rss RSS feed
serviceStatus Display the current status of one of your service checks
latestValue The latest value for a selected metric
Suggest Edits

Deleting a widget

 
deletehttps://api.serverdensity.io//users/v3/widgets/widgetId
curl -v -X DELETE https://api.serverdensity.io/users/v3/widgets/5278f5f576d3774043000000?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
widget_id = '5278f5f576d3774043000000'

delete_response = requests.delete(
    "https://api.serverdensity.io/users/widgets/{0}".format(widget_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
widget_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/users/widgets/#{widget_id}", 
    params
)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
widget_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
_id = client.widgets.delete(widget_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "5278f5f576d3774043000000"
}

Path Params

widgetId
string
required

The ID of the widget to delete

Body Params

token
string
required

Your API token

 
Suggest Edits

Listing all widgets

Get a list of every widget on your account.

 
gethttps://api.serverdensity.io//users/v3/widgets
curl -v -X GET https://api.serverdensity.io/users/v3/widgets?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

requests.get(
    'https://api.serverdensity.io/users/widgets',
    params = {'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/users/widgets', params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
widgets = client.widgets.list()


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "_id": "5457a1ff95fe35c63174751f",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "config": {
      "providerId": "joyent",
      "feedUrl": "https:\/\/help.joyent.com\/forums\/20715782-Current-System-Status\/posts.rss"
    },
    "dashboardId": "5457a1fad998d12f038b4567",
    "type": "cloudStatus"
  },
  {
  "_id": "1457a1ff95fe35c63174751f",
  "accountId": "4fa3c6ef22257d6c2f000000",
  "config": {
    "providerId": "joyent",
    "feedUrl": "https:\/\/help.joyent.com\/forums\/20715782-Current-System-Status\/posts.rss"
  },
  "dashboardId": "5457a1fad998d12f038b4567",
  "type": "cloudStatus"
  },
]

Query Params

token
string
required

Your API token

 
Suggest Edits

Updating a widget

 
puthttps://api.serverdensity.io//users/v3/widgets/widgetId
curl -v -X PUT https://api.serverdensity.io/users/v3/widgets/5457a1ff95fe35c63174751f?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data type=rss
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
widget_id = '5457a1ff95fe35c63174751f'

api_response = requests.put(
    'https://api.serverdensity.io/users/widgets/{0}'.format(widget_id),
    params={'token': token},
    json={"type": "rss"}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
widget_id = '5278f5f576d3774043000000'

params = {
    :query => {"token" => token},
    :body => {
        "type" => "rss"
    }        
}

response = HTTParty.put(
    "https://api.serverdensity.io/users/widgets/#{widget_id}", params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
widget_id = '22ddab237dff5cde07dc70a26e93c262'
data = {"type": "rss"}

client = ApiClient(token)
widget = client.widgets.update(widget_id, data)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_id": "5457a1ff95fe35c63174751f",
  "accountId": "532c053395fe35876a84b9e7",
  "config": {
    "providerId": "joyent",
    "feedUrl": "https://help.joyent.com/forums/20715782-Current-System-Status/posts.rss"
  },
  "dashboardId": "5457a1fad998d12f038b4567",
  "type": "rss"
}

Path Params

widgetId
string
required

ID of the widget to update

Body Params

token
string
required

Your API token

 
Suggest Edits

Viewing a widget

 
gethttps://api.serverdensity.io//users/v3/widgets/widgetId
curl -v -X GET https://api.serverdensity.io/users/v3/widgets/5457a1ff95fe35c63174751f?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

widget_id = '5457a1ff95fe35c63174751f'

api_response = requests.get(
    'https://api.serverdensity.io/users/widgets/{0}'.format(widget_id),
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
widget_id = '5457a1ff95fe35c63174751f'

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/users/widgets/#{widget_id}', params)

response.to_json
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
widget_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
widget = client.widget_id.view(widget_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_id": "5457a1ff95fe35c63174751f",
  "accountId": "532c053395fe35876a84b9e7",
  "config": {
    "providerId": "joyent",
    "feedUrl": "https://help.joyent.com/forums/20715782-Current-System-Status/posts.rss"
  },
  "dashboardId": "5457a1fad998d12f038b4567",
  "type": "cloudStatus"
}

Path Params

widgetId
string
required

ID of the widget to view

Query Params

token
string
required

Your API token

 
Suggest Edits

Duplicating a widget

 
posthttps://api.serverdensity.io//users/v3/widgets/duplicate/widgetId
curl -X POST https://api.serverdensity.io/users/v3/widgets/duplicate/532c055276d377cb05ef7b15?token=b97da80a41c4f61bff05975ee51eb1aa 
import json
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
widget_id = '5457a1ff95fe35c63174751f'

api_response = requests.post(
    'https://api.serverdensity.io/users/widgets/duplicate/{0}'.format(widget_id),
    params={'token': token},
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
widget_id = '5278f5f576d3774043000000'

params = {
    :query => {"token" => token},     
}

response = HTTParty.post(
    "https://api.serverdensity.io/users/widgets/duplicate/#{widget_id}", params)

response.to_json

# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
widget_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
widget = client.widgets.duplicate(widget_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "_id": "5457b3b495fe35d54d747520",
  "accountId": "5457a1fad998d12f038b4567",
  "owner": "4fa3c6ef22257d6c2f000000"
}

Path Params

widgetId
string
required

ID of the widget to duplicate

Body Params

token
string
required

Your API token

 
Suggest Edits

Configuring a widget

Widget json objects have a config field where the widget configuration is stored. The configuration depends on the widget type. This different configuration variants are described in this document.

 

cloudStatus

This widget type shows the status of some cloud vendors

cloudStatus Parameters

Parameters Description
providerId Name of the provider
amazon
digitalOcean
google
joyent
linode
rackspace
salesforce
softlayer
windowsAzure
feedUrl Url of the news feed. The feed needs to be one of the specified on the Cloud status widget feed url list page. If the feed you wish to use is not in this list you should use an RSS widget, which can be configured with any feed.

Example Configuration

{
  "providerId": “amazon”,
  "feedUrl": "http://status.aws.amazon.com/rss/cloudfront.rss"
}

graph

This widget shows time series data

graph Parameters

Parameters Required Type Description
requests No list of dicts Each dict in the list can contain the scope, metric, and tags fields.The scope field will contain the id(s) of the subject device/service or the regex filter to be used on the device/service list. The metric filed will contain the name of the metric being displayed. The tags field will contain the tagged instances that will be displayed for the selected metric
filter Yes dict Object containing the metrics to be graphed. The JSON representation to the left would graph all available apache stats.
type Yes string "line" for line a line graph. "area" for a stacked area graph.
tall No bool True makes the maximized view of the graph extra tall.
seriesStatesv3 No dict Contains the series configuration of a graph such as assigning series to the left or right axis or disabling them completely.

Example Configuration

"requests": [
  {
    "scope": [
      {
        "filter": "[1|2]"
      }
    ],
    "metric": "system.processes.number"
  },
  {
    "scope": [
      {
        "item": "5ad9d132b03e85d53165456a"
      }
    ],
    "tags": {
      "device_name": "*"
    },
    "metric": "system.disk.in_use"
  },
],
"type": "line"

rss

This widget shows the last entries from the specified RSS feed

rss Parameters

Parameters Required Type Description
feedUrl Yes string Url of the RSS news feed.

Example Configuration

{
  "feedUrl": "http://status.aws.amazon.com/rss/fps.rss"  
}

serviceStatus

This widget shows the current status of one of your service checks

Config Parameters

Parameters Required Type Description
serviceId Yes string Id of the service this widget will display information from.

Example Configuration

{
  "serviceId": "5457a1ff95fe35c63174751f"  
}

openAlerts

This widget shows the number of open alerts

openAlerts Parameters

entity Is a dictionary which is the definition of the subset of entities from which to count alerts.

Within entity the following parameters can be used.

Parameters Type Description
id string Id of the device or service or the name of the group. Use all for the whole account
name string Name of the device or group
type string What type it is. See the following types.
type > device string The id is from a device
type > deviceGroup string The id is from a deviceGroup
type > service string The id is from a service
type > serviceGroup string The id is from a service group
isGroup bool Depending if the ID is from a group.

Example Configurations

{
  "entity": {
    "id": "all",
    "name": "The entire account",
    "type": "all",
    "isGroup": false
  }
}
 
{
  "id": "5458c45276d3776004900000",
  "name": "test",
  "type": "device",
  "isGroup": false
}
 
{
  "id": "5358f95f76d377e876000000",
  "name": "www.serverdensity.com",
  "type": "service",
  "isGroup": false
}
 
{
  "id": "test_group",
  "name": "test_group",
  "type": "deviceGroup",
  "isGroup": true
}
 
{
  "id": "Monitored websites",
  "name": "Monitored websites",
  "type": "serviceGroup",
  "isGroup": true
}
Suggest Edits

Creating a tag

You can create new tags for devices and services. These tags are used to give permissions to set of users for them to be able to view these devices.

 
posthttps://api.serverdensity.io//inventory/tags
curl -v https://api.serverdensity.io/inventory/tags/?token=b97da80a41c4f61bff05975ee51eb1aa \
  --data name=newTag \ 
  --data color=#fff000
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"

api_response = requests.post(
    'https://api.serverdensity.io/inventory/tags',
    params={
        'token': token
    },
    data={
        'name': 'newTag',
        'color': '#fff000'
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"

params = {
    :query => {"token" => token},
    :body => {
      "name" => "newTag",
      "color" => "#fff000"
    }
}

response = HTTParty.post("http://api.serverdensity.io/inventory/tags", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('tags')->create("my tag");

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
data={
  'name': 'newTag',
  'color': '#fff000'
}

client = ApiClient(token)
tag = client.tags.create(data)

A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
        "_id": "5488258495fe35fb2d9abc58",
        "name": "newTag",
        "color": "#fff000",
        "updatedAt": "2016-02-10T10:50:44",
        "createdAt": "2016-02-10T10:50:44",
        "accountId": "5460a25972d377c3324420b2",
        "deleted": false
}

Body Params

token
string
required

Your API token

name
string
required

Name of the tag

color
string
required

The color of the tag in hexcode

 
Suggest Edits

Deleting a tag

 
deletehttps://api.serverdensity.io//inventory/tags
curl -v -X DELETE https://api.serverdensity.io/inventory/tags/51f931c9dba4bba36d001542?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
tag_id = '51f931c9dba4bba36d001542'

delete_response = requests.delete(
    "https://api.serverdensity.io/inventory/tags/{0}".format(tag_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
tag_id = '51f7eafcdba4bb235e000ae4'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/inventory/tags/#{tag_id}", 
    params
)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = '65o4ea65oe46ao4e5a';

$client->api('tags')->delete($id);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
tag_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
_id = client.tags.delete(tag_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "51f931c9dba4bba36d001542"
}

Body Params

token
string
required

Your API token

 
Suggest Edits

View all tags

View all available tags on the account.

 
gethttps://api.serverdensity.io//inventory/tags
curl -v -X GET https://api.serverdensity.io/inventory/tags?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

requests.get(
    'https://api.serverdensity.io/inventory/tags',
    params = {
        'token': token
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/inventory/tags', params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$client->api('tags')->all();

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'

client = ApiClient(token)
tags = client.tags.list()


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "_id": "5488258495fe35fb2d9abc58",
        "name": "uppsala",
        "color": "#c33b9b",
        "updatedAt": "2016-02-10T10:50:44",
        "createdAt": "2016-02-10T10:50:44",
        "accountId": "5460a25976d377c3324420b2",
        "deleted": false
    }
]

Query Params

token
string
required

Your API token

 
Suggest Edits

Updating a tag

 
patchhttps://api.serverdensity.io//inventory/tags
curl -v -X PUT https://api.serverdensity.io/inventory/tags/5457a1ff95fe35c63174751f?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data name=UpdatedLlama color=#f0f0f0
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
tag_id = '5457a1ff95fe35c63174751f'

r = requests.put(
    'https://api.serverdensity.io/inventory/tags/{0}'.format(tag_id),
    params={'token': token},
    data={
        "name": "UpdatedLlama",
        "color": "#f0f0f0",
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
tag_id = '5278f5f576d3774043000000'

params = {
    :query => {"token" => token},
    :body => {
        "name" => "UpdatedLlama",
        "color" => "#f0f0f0"
    }        
}

response = HTTParty.put(
    "https://api.serverdensity.io/inventory/tags/#{tag_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = '2342342513aa34a34a4a';
$fields = array(
    'name' => 'tag',
    'color' => '#ffffff'
);

$client->api('tags')->update($id, $fields);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
tag_id = '22ddab237dff5cde07dc70a26e93c262'
data={
  "name": "UpdatedLlama",
  "color": "#f0f0f0",
}

client = ApiClient(token)
tag = client.tags.update(tag_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "color": "#f0f0f0",
    "name": "UpdatedLlama",
    "updatedAt": "2016-02-10T12:38:33",
    "accountId": "5460a25976d377c3324420b2",
    "_id": "5488373095fe3569108b456a"
}

Body Params

token
string
required

Your API token

name
string

Name of the tag

color
string

The color of the tag in hexcode

 
Suggest Edits

Viewing an individual tag

 
gethttps://api.serverdensity.io//inventory/tags/tagId
curl -v -X GET https://api.serverdensity.io/inventory/tags/51f6585e11f144673749afbb?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

token = "b97da80a41c4f61bff05975ee51eb1aa"
tag_id = '51f6585e11f144673749afbb'

api_response = requests.get(
    'https://api.serverdensity.io/inventory/tags/{0}'.format(tag_id),
    params = {'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
tag_id = '5457a1ff95fe35c63174751f'

params = {:query => {"token" => token}}

response = HTTParty.get("https://api.serverdensity.io/inventory/tags/#{tag_id}", params)

response.to_json
<?php
namespace serverdensity;
require __DIR__.'/vendor/autoload.php';
use serverdensity\Client;

$TOKEN = 'your authentication token here';

$client = new Client();
$client->authenticate($TOKEN);

$id = '2342342513aa34a34a4a';

$client->api('tags')->view($id);
$client->api('tags')->find('namehere');
$client->api('tags')->findAll(['name', 'here']);

?>
# on pypi as sd-python-wrapper
from serverdensity.wrapper import ApiClient

token = '2dfae5bf81f65492a40569d39b29ffa3'
tag_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
tag = client.tags.view(tag_id)


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "_id": "5488258495fe35fb2d9abc58",
    "name": "uppsala",
    "color": "#c33b9b",
    "updatedAt": "2016-02-10T10:50:44",
    "createdAt": "2016-02-10T10:50:44",
    "accountId": "5460a25976d377c3324420b2",
    "deleted": false
}

Path Params

tagId
string
required

The ID of the tag to view

Query Params

token
string
required

Your API token

 
Suggest Edits

Create a token

 
posthttps://api.serverdensity.io//tokens/
curl -X POST 'https://api.serverdensity.io/tokens/?token=b97da80a41c4f61bff05975ee51ea2bc' \  
--data 'tokenName=Test Token'
import requests

api_response = requests.post(
    'https://api.serverdensity.io/tokens/',
    params={
        'token':'b97da80a41c4f61bff05975ee51ea2bc'
    },
    data={
        "tokenName": "Llama"
    }
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51ea2bc"
params = {
    :query => {"token" => token},
    :body => {"tokenName" => "Llama"}
}

response = HTTParty.post("https://api.serverdensity.io/tokens/", params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "token_data": {
        "userId": "51f65a19dba4bbf15d000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "date_issued": {
            "sec": 1375106903,
            "usec": 49000
        },
        "tokenName": "Llama script",
        "token": "b97da80a41c4f61bff05975ee51eb1aa"
    }
}

Query Params

token
string
required

Your API token

Body Params

tokenName
string

The name of your new token

 
Suggest Edits

Get all tokens

 
gethttps://api.serverdensity.io//tokens/
curl -X GET 'https://api.serverdensity.io/tokens/?token=b97da80a41c4f61bff05975ee51eb1aa'
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

requests.get(
    'https://api.serverdensity.io/tokens/',
    params = {'token': token}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/tokens/', params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[{
    "token_data": {
        "userId": "51f65a19dba4bbf15d000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "date_issued": {
            "sec": 1375106903,
            "usec": 49000
        },
        "tokenName": "Llama script",
        "token": "b97da80a41c4f61bff05975ee51eb1aa"
    }
}
{
    "token_data": {
        "userId": "51f65a19dba4bbf15d000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "date_issued": {
            "sec": 1375106953,
            "usec": 49000
        },
        "tokenName": "Llama script 2",
        "token": "b97da80a41c4f61bff05975ee51dead1"
    }
}]

Query Params

token
string
required

Your API token

 
Suggest Edits

Delete a token

 
deletehttps://api.serverdensity.io//tokens/tokenId
curl -X DELETE 'https://api.serverdensity.io/tokens/b97da80a41c4f61bff05975ee51dead1?token=b97da80a41c4f61bff05975ee51eb1aa'
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
token_id = 'b97da80a41c4f61bff05975ee51dead1'

delete_response = requests.delete(
    "https://api.serverdensity.io/tokens/{0}".format(token_id),
    params={'token': token}
)
require "httparty"

token = "901de5c241a6e879c1c6f0b27459d3f1"
token_id = 'b97da80a41c4f61bff05975ee51dead1'

params = {
    :query => {"token" => token},
}

response = HTTParty.delete(
    "https://api.serverdensity.io/tokens/#{token_id}", 
    params
)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"token":"b97da80a41c4f61bff05975ee51dead1"}

Query Params

token
string
required

Your API token

tokenId
string
required

The token you wish to delete.

 
Suggest Edits

Listing token by ID

 
gethttps://api.serverdensity.io//tokens/tokenId
curl -X GET'https://api.serverdensity.io/tokens/b97da80a41c4f61bff05975ee51dead1?token=b97da80a41c4f61bff05975ee51eb1aa' 
import requests

token_id = '5278f5f576d3774043000000'

api_response = requests.get(
    'https://api.serverdensity.io/tokens/{0}'.format(token_id),
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'}
)
require "httparty"

token = "b97da80a41c4f61bff05975ee51eb1aa"
token_id = '5278f5f576d3774043000000'

params = {:query => {"token" => token}}

response = HTTParty.get('https://api.serverdensity.io/tokens/#{token_id}', params)

response.to_json
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
	"accountName":"example",
	"username":"llama",
	"accountId":"4fa3c6ef22257d6c2f000000",
	"userId":"51f65a19dba4bbf15d000000"
}

Query Params

token
string
required

Your API token

tokenId
string
required

The token that you are listing details for