Server Density API Docs

discard

Search results for "{{ search.query }}"

No results found for "{{search.query}}".
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.

 
post https://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)
)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "token_data": {
        "userId": "51f65a19dba4bbf15d000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "date_issued": {
            "sec": 1375106903,
            "usec": 49000
        },
        "tokenName": "Llama script",
        "token": "b97da80a41c4f61bff05975ee51eb1aa"
    }
}

Body JSON

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.

 
delete https://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://serverdensity.io/tokens/{0}".format(token_to_delete),
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa'
    }
)
require "httparty"

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

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

response.to_json
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "token": "901de5c241a6e879c1c6f0b27459d3f1"
}

Path Params

token_to_delete
string
required

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

Body JSON

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.

 
get https://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.
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
< 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.

 
post https://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')
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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 JSON

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.

hostname
string

Device’s hostname

installedRAM
string

RAM installed

os
string

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

privateIPs
array

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

publicIPs
array

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

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.

 
delete https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "51f931c9dba4bba36d001542"
}

Body JSON

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.

 
get https://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()
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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 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.

 
get https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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.

 
put https://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'}
)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 JSON

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

 
get https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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

 
get https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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

 
get https://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();

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

Path Params

token
string
required

Your API token

 
Suggest Edits

Creating a service

 
post https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 JSON

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

 
delete https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "51f931c9dba4bba36d001542"
}

Path Params

serviceId
string
required

The ID of your service.

Body JSON

token
string
required

Your API token.

 
Suggest Edits

Listing services

 
get https://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()
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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.

 
get https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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

 
put https://api.serverdensity.io/inventory/services/serviceId
curl -v -X PUT http://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "name": "Changed Llama",
    "updatedAt": "2016-02-31T16:25:22",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "_id": "51f932d0dba4bbf15d001219"
}

Path Params

serviceId
string
required

The ID of your service.

Body JSON

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

 
get https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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

 
get https://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();

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

Path Params

token
string
required

Your API token

 
Suggest Edits

Creating an alert

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

 
post https://api.serverdensity.io/alerts/configs
curl -v -X POST https://api.serverdensity.io/alerts/configs/?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data subjectId=520dee51cbda5de279000013 \
     --data subjectType=device \
     --data section=system \
     --data field=loadAvrg \
     --data comparison=gte \
     --data value=0 \
     --data recipients='[{"type":"user","id":"520dec7ecbda5d317300000a","actions":["sms","email"]}]' \
     --data wait='{"seconds": 60,"enabled":true,"displayUnits": "s"}' \
     --data repeat='{"seconds": 300,"enabled":true,"displayUnits": "s"}' \
     --data fix=true
import json
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'

api_response = requests.post('https://api.serverdensity.io/alerts/configs',
    params={'token': token},
    json={
        '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'
    }
)
require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"
params = {
    :query => {"token" => token},
    :body => {
        'subjectId' => '520dee51cbda5de279000013',
        'subjectType' => 'device',
        'section' => 'system',
        'field' => 'loadAvrg',
        'comparison' => 'gte',
        'value' => 0,
        'recipients' => JSON.dump(
            [{
                "type" => "user",
                "id" =>"520dec7ecbda5d317300000a",
                "actions" => [
                    "sms",
                    "email"
                ]
            }]
        ),
        'wait' => JSON.dump(
            {
                "seconds" => 60,
                "enabled" => true,
                "displayUnits" => "s"
            }
        ),
        'repeat' => JSON.dump(
            {
                "seconds" => 300,
                "enabled" => true,
                "displayUnits" => "s"
            }
        ),
        'fix' => true
    }
}

response = HTTParty.post("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);
$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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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"
}

Body JSON

token
string
required

Your API token

subjectId
string
required

The ID of the subject e.g. the device/service ID or the group name for group alerts

subjectType
string
required

The type of the subject - device or service for individual alerts, or deviceGroup or serviceGroup for group alerts

subject
string
required

Is either null or contains a string of a path, or a name of process for instance. It can also be ‘ALL’ for average over all paths eg for disk usage.

enabled
boolean
required

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

section
string
required

The metric section

field
string
required

The metric sub-section

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
required

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

wait
string
required

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

repeat
string
required

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

fix
boolean
required

Whether the alert is fixed or not.

fullField
string
required

Required if the alert contains a subject. This is usually a combination of section and field. A full list of all fullFields is available in the the Appendix

 

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

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.

Actions is optional for pagerduty or webhook type

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

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

delete_response = requests.delete(
    "https://api.serverdensity.io/alerts/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/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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "523599f19711f423690003e4"
}

Path Params

alertId
string
required

The ID of the alert to be deleted

Body JSON

token
string
required

Your API token

 
Suggest Edits

Listing all alerts

Get a list of all configured alerts on your account.

 
get https://api.serverdensity.io/alerts/configs
curl -v -X GET https://api.serverdensity.io/alerts/configs/?token=b97da80a41c4f61bff05975ee51eb1aa\&filter='\{"field":"loadAvrg"\}'
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();

?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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 subject

Get a list of all configured alerts for a specific subject (device or service).

 
get https://api.serverdensity.io/alerts/configs/subjectId
curl -v -X GET https://api.serverdensity.io/alerts/configs/52037df285ce7525c4f5813a?subjectType=device\&token=b97da80a41c4f61bff05975ee51eb1aa
import requests

subject_id = '52037df285ce7525c4f5813a'

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

token = 'b97da80a41c4f61bff05975ee51eb1aa'
subject_id = '52037df285ce7525c4f5813a'

params = {:query => {
    "token" => token 
    "subjectType": "device"
}
response = HTTParty.get('https://api.serverdensity.io/alerts/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 = '65oae4a65oe46a5oe4ao';
$type = 'device'

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

?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_id": "5203a041dba4bb6010000000",
        "accountId": "4fa3c6ef22257d6c2f000000",
        "comparison": "gt",
        "createdAt": {
            "sec": 1375969345,
            "usec": 0
        },
        "deleted": false,
        "enabled": true,
        "field": "loadAvrg",
        "fix": true,
        "fullField": "system-loadAvrg",
        "group": "",
        "recipients": [
            {
                "id": "52037dd6dba4bbc014000349",
                "type": "user",
                "actions": [
                    "email"
                ]
            },
            {
                "id": "52037dd6dba4bb391e00009e",
                "type": "user",
                "actions": [
                    "email"
                ]
            }
        ],
        "repeat": {
            "seconds": 0,
            "enabled": false,
            "displayUnits": "s"
        },
        "section": "system",
        "subject": null,
        "subjectId": "52037df285ce7525c4f5813a",
        "subjectType": "device",
        "updatedAt": {
            "sec": 1375969354,
            "usec": 0
        },
        "valid": true,
        "value": "2",
        "wait": {
            "seconds": 0,
            "enabled": false,
            "displayUnits": "s"
        }
    }
]

Path Params

subjectId
string
required

The ID of the subject e.g. the device ID

Query Params

token
string
required

Your API token.

subjectType
string
required

The type of the subject - device or service

 
Suggest Edits

Updating alerts

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

 
put https://api.serverdensity.io/alerts/configs/alertId
curl -v -X PUT https://api.serverdensity.io/alerts/configs/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa \
     --data value=5 \
     --data recipients='[{"type":"user","id":"520dec7ecbda5d317300000a","actions":["email"]}]'
import requests

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

api_response = requests.put(
    'https://api.serverdensity.io/alerts/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.put(
    "https://api.serverdensity.io/alerts/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" =>
        [
            "type":"user",
            "id":"520dec7ecbda5d317300000a",
            "actions": ["email"]
        ],
);

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

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

?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 service to update

Body JSON

token
string
required

Your API token.

subjectId
string

The ID of the subject e.g. the device/service ID or the group name for group alerts

subjectType
string

The type of the subject - device or service for individual alerts, or deviceGroup or serviceGroup for group alerts

enabled
boolean

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

section
string

The metric section

field
string

The metric sub-section

comparison
string

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

value
string

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

 

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 an alert by ID

 
get https://api.serverdensity.io/alerts/configs/alertId
curl -v -X GET https://api.serverdensity.io/alerts/configs/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa
import requests

alert_id = '523599f19711f423690003e4'

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

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

params = {:query => {
    "token" => token 
}
response = HTTParty.get('https://api.serverdensity.io/alerts/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);

?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 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.

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

token = 'b97da80a41c4f61bff05975ee51eb1aa'
alert_id = '523599f19711f423690003e4'

api_response = requests.put(
    'https://api.serverdensity.io/alerts/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.put(
    "https://api.serverdensity.io/alerts/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);

?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 JSON

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.

 
get https://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"}'"
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')

?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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.

 

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.

 
get https://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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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.

 
get https://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
)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No code 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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
No code examples available

Body JSON

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

 
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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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, for a specific subject (device or service) over a specific time range.

 
gethttps://api.serverdensity.io/metrics/definitions
curl -v -X GET "https://api.serverdensity.io/metrics/definitions/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa&start=2013-09-15T17:00:00Z&end=2013-09-15T18:00:00Z"
import requests

subject_id = '523599f19711f423690003e4'

api_response = requests.get(
    'https://api.serverdensity.io/metrics/definitions/{0}'.format(subject_id),
    params={
        'token': 'b97da80a41c4f61bff05975ee51eb1aa',
        'start' : '2013-09-15T17:00:00Z',
        'end': '2013-09-15T18:00:00Z'
    }
)
require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'
subject_id = '523599f19711f423690003e4'

params = {:query => {
        'start' => '2013-09-15T17:00:00Z',
        'end' => '2013-09-15T18:00:00Z',
        'token' => token
}
response = HTTParty.get('https://api.serverdensity.io/metrics/definitions/#{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 = "76oeu57a5765a76e5a7";

$client->api('metrics')->available($id, time()-7200, time());

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

start = dt.datetime.now() - timedelta(hours=2)
end = dt.datetime.now()

token = '2dfae5bf81f65492a40569d39b29ffa3'
device_id = '22ddab237dff5cde07dc70a26e93c262'

client = ApiClient(token)
metrics = client.metrics.available(device_id, start, end)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "tree": [
            {
                "name": "CPU0",
                "tree": [
                    {
                        "name": "Soft",
                        "unit": "%",
                        "key": "soft"
                    },
                    {
                        "name": "Guest",
                        "unit": "%",
                        "key": "guest"
                    },
                    {
                        "name": "Nice",
                        "unit": "%",
                        "key": "nice"
                    }
                ],
                "key": "CPU0"
            }
        ],
        "name": "CPU stats",
        "key": "cpuStats"
    },
    {
        "name": "Load average",
        "unit": false,
        "key": "loadAvrg"
    },
    {
        "key": "memory",
        "name": "Memory",
        "tree": [
            {
                "name": "Cached used",
                "unit": "MB",
                "key": "memPhysCached"
            },

            {
                "name": "Swap used",
                "unit": "MB",
                "key": "memSwapUsed"
            }
        ]
    },
    {
        "name": "Processes",
        "unit": false,
        "key": "processes"
    }
]

Query Params

token
string
required

Your API token

subjectId
string
required

The ID of the subject to get the definitions for, e.g. a device ID.

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

 
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/graphs
# Filter by network traffic, eth0, received MB/s

curl -v -X GET https://api.serverdensity.io/metrics/graphs/523599f19711f423690003e4?token=b97da80a41c4f61bff05975ee51eb1aa\&start=2013-09-15T17:00:00Z\&end=2013-09-15T18:00:00Z\&filter='\{"networkTraffic":\{"eth0":\["rxMByteS"\]\}\}'
# Filter by network traffic, eth0, received MB/s

import json
from datetime import datetime, timedelta

import requests

subject_id = '523599f19711f423690003e4'
token = 'b97da80a41c4f61bff05975ee51eb1aa'

# 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/graphs/{0}'.format(subject_id),
    params={
        'token': token,
        'start' : start.isoformat(),
        'end': end.isoformat(),
        'filter': json.dumps(filter)
    }
)

require "httparty"
token = 'b97da80a41c4f61bff05975ee51eb1aa'
subject_id = '523599f19711f423690003e4'

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/definitions/#{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 = "76oeu57a5765a76e5a7";

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

$client->api('metrics')->metrics($id, $filter, time()-7200, time());

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

start = dt.datetime.now() - timedelta(hours=2)
end = dt.datetime.now()

token = '2dfae5bf81f65492a40569d39b29ffa3'
device_id = '22ddab237dff5cde07dc70a26e93c262'

filter = {
    'networkTraffic': {
        'eth0': ['rxMByteS']
    }
}

client = ApiClient(token)
metrics = client.metrics.get(device_id, start, end, filter)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "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

subjectId
string
required

The ID of the subject to get the definitions for, e.g. a device ID.

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

 

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.

Parameters: Filter

For device IDs these are the following parameters you can filter at a top level. The filter allows you to return a specific metric (e.g. network traffic), filtered further by a item (e.g. eth0) and sub metric (received MB/s). Please refer to the response given at Available metrics if you need to filter further than that.

Parameter Description
cpuStats CPU statistics
diskUsage Disk usage
ioStats IO statistics
loadAvrg The Average load
memory Amount of memory use
networkTraffic Network bandwidth
processes The amount processes running
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());
?>
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "_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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "5278f5f576d3774043000000"
}

Path Params

userId
string
required

The ID of the user to delete

Body JSON

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()
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "firstName": "James",
    "updatedAt": "2016-02-05T13:53:51",
    "_id": "5278f5f576d3774043000000"
}

Path Params

userId
string
required

ID of the user you're updating

Body JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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/
curl -X POST https://api.serverdensity.io/alerts/postbacks?token=b97da80a41c4f61bff05975ee51eb1aa \
    --data hash=be8c0635f5fdd4da4f0573601a67a9e4 \
    --data payload='{"agentKey": "23ddab267dff7cde05dc20a28e93c272", "os": "linux", "networkTraffic": {"lo": {"trans_bytes": "0", "recv_bytes": "0"}, "eth0": {"trans_bytes": "25603", "recv_bytes": "5861"}}}' \
    --header "X-Forwarded-Host: example.serverdensity.io"
    
##
## Custom metrics
##

curl -X POST https://api.serverdensity.io/alerts/postbacks?token=b97da80a41c4f61bff05975ee51eb1aa \
    --data hash=3cb14ab69c100a7c077c40bffce48424 \
    --data payload='{"agentKey": "23ddab267dff7cde05dc20a28e93c272", "plugins": {"MyCustomMetric": {"key1": "1", "key2": "true"}, "AnotherCustomMetric": {"Cheese": "25603", "StringValue": "yes"}}}' \
    --header "X-Forwarded-Host: example.serverdensity.io"
import json
from hashlib import md5

import requests

payload = json.dumps({
    "agentKey": "23ddab267dff7cde05dc20a28e93c272",
    "os": "linux",
    "networkTraffic": {
        "lo": {"trans_bytes": "0", "recv_bytes": "0"},
        "eth0": {"trans_bytes": "25603", "recv_bytes": "5861"}
    }
})
payload_hash = md5(payload).hexdigest()
headers = {'X-Forwarded-Host': 'example.serverdensity.io'}

api_response = requests.post(
    'https://api.serverdensity.io/alerts/postbacks',
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'},
    data={
        'hash': payload_hash,
        'payload': payload,
    },
    headers=headers
)

##
## Custom metrics
##

import json
from hashlib import md5

import requests

payload = json.dumps({
    "agentKey": "23ddab267dff7cde05dc20a28e93c272",
    "plugins": {
        "MyCustomMetric": {"key1": "1", "key2": "true"},
        "AnotherCustomMetric": {"Cheese": "25603", "StringValue": "yes"}
    }
})
payload_hash = md5(payload).hexdigest()
headers = {'X-Forwarded-Host': 'example.serverdensity.io'}

api_response = requests.post(
    'https://api.serverdensity.io/alerts/postbacks',
    params={'token': 'b97da80a41c4f61bff05975ee51eb1aa'},
    data={
        'hash': payload_hash,
        'payload': payload,
    },
    headers=headers
)

require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"

payload = JSON.dump({
    "agentKey" => "23ddab267dff7cde05dc20a28e93c272",
    "os" => "linux",
    "networkTraffic" => {
        "lo" => {"trans_bytes" => "0", "recv_bytes" => "0"},
        "eth0" => {"trans_bytes" => "25603", "recv_bytes" => "5861"}
    }
})
payload_hash = Digest::MD5.hexdigest(payload)

params = {
    :query => {"token" => token},
    :body => {
        "hash" => payload_hash,
        "payload" => payload
    },
    :headers => headers = {'X-Forwarded-Host' => 'example.serverdensity.io'}
}

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

response.to_json

##
## Custom metrics
##

require "httparty"
require "json"

token = "b97da80a41c4f61bff05975ee51eb1aa"

payload = JSON.dump({
    "agentKey" => "23ddab267dff7cde05dc20a28e93c272",
    "plugins" => {
        "MyCustomMetric" => {"key1" => "1", "key2" => "true"},
        "AnotherCustomMetric" => {"Cheese" => "25603", "StringValue" => "yes"}
    }
})
payload_hash = Digest::MD5.hexdigest(payload)

params = {
    :query => {"token" => token},
    :body => {
        "hash" => payload_hash,
        "payload" => payload
    },
    :headers => headers = {'X-Forwarded-Host' => 'example.serverdensity.io'}
}

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

response.to_json
<?
// Example for custom metrics
$agentKey = '23ddab267dff7cde05dc20a28e93c272';
$token = 'b97da80a41c4f61bff05975ee51eb1aa';
$acc_name 'example';

$payload = '{"agentKey": , $agentKey "plugins": {"MyPlugin": {"users": "5", "hats": "3"}}}';
$hash = md5($payload);

$data = array("payload" => $payload, "hash" => $hash);                                                      
$ch = curl_init('https://api.serverdensity.io/alerts/postbacks?token=');                                                                      
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                                     
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);                                                                  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                                      
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-Forwarded-Host: $acc_name.serverdensity.io'
));

curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                     

$result = curl_exec($ch);
echo $result;

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

Body JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "name":"dashname",
  "accountId":"4fa3c6ef22257d6c2f000000",
  "_id":"545742cfd4d3680e0a3348a9"
}

Body JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "5278f5f576d3774043000000"
}

Path Params

dashboardId
string
required

ID of the dashboard to delete

Body JSON

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()
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "_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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "name": "mynewdashboard2",
    "accountId": "4fa3c6ef22257d6c2f000000",
    "_id": "54525649d4d368e620334887"
}

Path Params

dashboardId
string
required

The ID of the dashboard to update.

Body JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "_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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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 JSON

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/widgets
curl -v -X POST https://api.serverdensity.io/users/widgets/?token=b97da80a41c4f61bff05975ee51eb1aa \
  --data type=elasticGraph \
  --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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "_id": "5457b3b495fe35d54d747520",
  "type": "elasticGraph",
  "dashboardId": "5457a1fad998d12f038b4567",
  "accountId": "4fa3c6ef22257d6c2f000000"
}

Body JSON

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
elasticGraph Graph widget with time series data that dynamically selects the devices/services that will be displayed based on a search term
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
Suggest Edits

Deleting a widget

 
deletehttps://api.serverdensity.io/users/widgets/widgetId
curl -v -X DELETE https://api.serverdensity.io/users/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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "5278f5f576d3774043000000"
}

Path Params

widgetId
string
required

The ID of the widget to delete

Body JSON

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/widgets
curl -v -X GET https://api.serverdensity.io/users/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()
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "_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/widgets/widgetId
curl -v -X PUT https://api.serverdensity.io/users/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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "_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 JSON

token
string
required

Your API token

 
Suggest Edits

Viewing a widget

 
gethttps://api.serverdensity.io/users/widgets/widgetId
curl -v -X GET https://api.serverdensity.io/users/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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "_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/widgets/duplicate/widgetId
curl -X POST https://api.serverdensity.io/users/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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "_id": "5457b3b495fe35d54d747520",
  "accountId": "5457a1fad998d12f038b4567",
  "owner": "4fa3c6ef22257d6c2f000000"
}

Path Params

widgetId
string
required

ID of the widget to duplicate

Body JSON

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"
}

elasticGraph

This widget shows time series data from a list of devices or services dynamically generated.

elasticGraph Parameters

Parameters Required Type Description
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.
searchFilter Yes string The search query that will be used to find devices, services or both (dependant on the sectionFilter). All devices or services return by the search query will graph the selected metrics.
tall No bool True makes the maximized view of the graph extra tall.
seriesStates No dict Contains the series configuration of a graph such as assigning series to the left or right axis or disabling them completely.
sectionFilter No string "devices" or "services" to graph only devices or services respectively. Use "all" not to filter.

Example Configurations

{
  "searchFilter": "s",
  "sectionFilter": "all",
  "filters": {
    "time": "all"
  },
  "seriesStates": {
    "series": {
      "5358f95f76d377e876000000: Australia: Sydney": "left",
      "5358f95f76d377e876000000: Brazil: Sao Paulo": "right",
      "5358f95f76d377e876000000: Chile: Vina del Mar": "disabled"
    }
  }
}
{
  "apache":"all"
}

graph

This widget shows time series data

graph Parameters

Parameters Required Type Description
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.
seriesStates 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

{
  "graphs": [
    {
      "filters": {
        "time": "all"
      },
      "type": "service",
      "serviceId": "5358f95f76d377e876000000"
    },
  ],
  "seriesStates": {
    "series": {
      "5358f95f76d377e876000000: Australia: Sydney": "left",
      "5358f95f76d377e876000000: Brazil: Sao Paulo": "right",
      "5358f95f76d377e876000000: Chile: Vina del Mar": "disabled"
    }
  },
  "type": "line",
  "tall": false
}

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
        "_id": "5488258495fe35fb2d9abc58",
        "name": "newTag",
        "color": "#fff000",
        "updatedAt": "2016-02-10T10:50:44",
        "createdAt": "2016-02-10T10:50:44",
        "accountId": "5460a25972d377c3324420b2",
        "deleted": false
}

Body JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_id": "51f931c9dba4bba36d001542"
}

Body JSON

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()
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "_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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "color": "#f0f0f0",
    "name": "UpdatedLlama",
    "updatedAt": "2016-02-10T12:38:33",
    "accountId": "5460a25976d377c3324420b2",
    "_id": "5488373095fe3569108b456a"
}

Body JSON

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)
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "_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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "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 JSON

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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[{
    "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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{"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
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
	"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