Introduction

These pages document the HTTP API exposed by the OpsDash SaaS version. If you’re looking instead for the API for the self-hosted version of OpsDash, that can be found here.

We’re constantly adding more API endpoints to the OpsDash SaaS version, with the intention of providing more opportunities for automation and scripting. Write to us at api-team@rapidloop.com with your inputs and suggestions.

If you’re looking to send in custom metrics, you might also be interested in the StatsD and Graphite interfaces exposed by the OpsDash Smart Agent.

API Conventions

All API calls are made over https to various endpoint URLs, all having the base of https://api.opsdash.com/v1/.
The v1 denotes the current version of the API.
The API endpoints support HTTP/2 and require https.
All calls use the HTTP method POST.
All API calls require the API key, which can be got from the Account Info page.
See the Standard Reponses section below for the format of responses returned by the API.

General APIs

These APIs allow you to query the alert status, and to send in custom metric data.

Report

curl -X POST \
  --data-binary @- \
  https://api.opsdash.com/v1/report/metrics <<EOBODY
{
  "apikey":  "your-api-key",
  "source":  "my-app-backend",
  "type":    2,
  "at":      1487070508,
  "metrics": [
    "s3.upload.time",
    "3.14"
  ]
}
EOBODY

import urllib2, json

data = json.dumps({
    'apikey':  'your-api-key',
    'source':  'my-app-backend',
    'type':    2,
    'at':      1487070508,
    'metrics': [
        's3.upload.time',
        '3.14'
    ]
})
body = urllib2.urlopen('https://api.opsdash.com/v1/report/metrics', data)
response = json.load(body)

var request = require('request');

var options = {
  uri: 'https://api.opsdash.com/v1/report/metrics',
  method: 'POST',
  json: {
    'apikey':  'your-api-key',
    'source':  'my-app-backend',
    'type':    2,
    'at':      (new Date).getTime()/1000 | 0,
    'metrics': [
      's3.upload.time',
      '3.14'
    ]
  }
};

request(options, function (error, response, body) {
  console.log(response.statusCode, body);
});

{}

Report the value of one or more (custom) metrics that belong to a (custom) source. If the source and/or metric does not exist already, it will be created.

Note that once a source is created, it will be monitored for uptime by default, unless explicitly overridden in the notification settings.

Request

POST https://api.opsdash.com/v1/report/metrics

Body

The request body must contain a valid JSON object with the following keys:

Key	Type	Description
apikey	string	Required. A valid API key from your Account Info page.
source	string	Required. The name of the source under which to report this metric. Must be within 255 characters consisting only of alphanumeric characters, “_”, “.” and “-”.
type	integer	Required. The type of the source. Valid values are 0 (server), 1 (service) and 2 (custom source).
at	integer	Required. Timestamp as number of seconds since 1 Jan 1970 UTC.
metrics	array	Required. Must have an even number of elements, and at least 2. Each element must be a string. See below for the contents of this array.

All the metrics reported in a single call will belong to the same source and have the same timestamp.

The metrics Array

The first (and every odd) element of the array is the name of the metric. This cannot be empty and must be within 128 characters not containing “<”, “>” or space.

The second (and every even) element of the array is the value of the corresponding metric, formatted as a string. For example: "-3.14", "1048576".

Response

This API returns an empty JSON object on success.

See the Standard Responses section for error responses.

Status

curl -X POST \
  --data-binary @- \
  https://api.opsdash.com/v1/status <<EOBODY
{
  "apikey": "your-api-key"
}
EOBODY

import urllib2, json

data = json.dumps({
    'apikey': 'your-api-key'
})
body = urllib2.urlopen('https://api.opsdash.com/v1/status', data)
response = json.load(body)

var request = require('request');

var options = {
  uri: 'https://api.opsdash.com/v1/status',
  method: 'POST',
  json: {
    'apikey': 'your-api-key'
  }
};

request(options, function (error, response, body) {
  console.log(response.statusCode, body);
});

{
  "down": [
    {
      "source": "node-10",
      "last": 1488593280
    }
  ],
  "breach": [
    {
      "dashid": 8,
      "dashname": "Web Servers Overview",
      "graphid": 92,
      "graphname": "Load Averages",
      "source": "node-2",
      "metric": "sys.os.loadavg",
      "combine": 0,
      "breachtype": "warnub"
    },
    {
      "dashid": 10,
      "dashname": "Cluster Overview",
      "graphid": 125,
      "graphname": "Running Processes",
      "source": "web-group",
      "metric": "sys.os.procs.running",
      "combine": 2,
      "breachtype": "warnlb"
    },
    {
      "dashid": 14,
      "dashname": "mysql-01",
      "graphid": 245,
      "graphname": "Processes",
      "source": "mysql-01",
      "metric": "sys.os.procs.zombie",
      "combine": 0,
      "breachtype": "critlb"
    }
  ]
}

The alert status of the servers and services monitored by OpsDash can be retrieved by this API. The information returned by this API corresponds to that displayed in the Open Alerts page.

Request

POST https://api.opsdash.com/v1/status

Body

The request body must contain a valid JSON object with the following keys:

Key	Type	Description
apikey	string	Required. A valid API key from your Account Info page.

Response

The successful response is a JSON object having the following keys:

Key	Type	Description
down	array	An array of “down” objects, each representing a source that is down. See table below. Will be present only if any sources are down.
breach	array	An array of “breach” objects, each representing a metric that has breached an upper/lower warning/critical threshold. See table below. Will be present only if there are any breaches.

Each “down” object has the following keys:

Key	Type	Description
source	string	The name of the source that is down.
last	integer	The time when the source was last heard from, as the number of seconds from 1 Jan 1970 UTC.

Each “breach” object has the following keys:

Key	Type	Description
dashid	integer	Unique identifier of the dashboard which contains the graph with the breached metric.
dashname	string	The name of the dashboard. For system-generated dashboards, this will be the name of the source or sourcegroup.
graphid	integer	Unique identifier of the graph.
graphname	string	The title of the graph.
source	string	The source or the sourcegroup (see “combine” key below) involved in the breach.
metric	string	The metric involved in the breach.
combine	integer	If 0, then “source” is the name a source. If 1, then it is a sourcegroup, and the data series denotes the average. If 2, then it is a sourcegroup, and the data series denotes the sum.
breachtype	string	The type of breach that occured. Value is one of: “critlb”, “warnlb”, “warnub” or “critub”, and indicates which threshold was breached. “lb” stands for lower bound, and “ub” for upper bound.

See the Standard Responses section for error responses.

Note that the JSON response body may not be pretty-printed as shown in the example.

Source APIs

These APIs allow you to list all sources, as well as delete them. Note that there is no explicit API to create a source – it is automatically created when OpsDash first sees a metric from a previously unknown source.

List

curl -X POST \
  --data-binary @- \
  https://api.opsdash.com/v1/sources/list <<EOBODY
{
  "apikey": "your-api-key"
}
EOBODY

import urllib2, json

data = json.dumps({
    'apikey': 'your-api-key'
})
body = urllib2.urlopen('https://api.opsdash.com/v1/sources/list', data)
response = json.load(body)

var request = require('request');

var options = {
  uri: 'https://api.opsdash.com/v1/sources/list',
  method: 'POST',
  json: {
    'apikey': 'your-api-key'
  }
};

request(options, function (error, response, body) {
  console.log(response.statusCode, body);
});

{
  "sources": [
    {
      "name": "mysql-node-02",
      "type": "server",
      "last": 1488651424
    },
    {
      "name": "mysql-slave",
      "type": "mysql",
      "last": 1488651424,
      "reporter": "mysql-node-02"
    }
  ]
}

The details of all sources monitored by OpsDash can be retrieved by this API.

Request

POST https://api.opsdash.com/v1/sources/list

Body

The request body must contain a valid JSON object with the following keys:

Key	Type	Description
apikey	string	Required. A valid API key from your Account Info page.

Response

The successful response is a JSON object having the following keys:

Key	Type	Description
sources	array	An array of “source” objects, each representing a source. See table below.

Each “source” object has the following keys:

Key	Type	Description
name	string	The name of the source.
type	string	The type of the source. For servers, it will be “server”. Otherwise it will be the value of the “type” field in the agent configuration, like “mysql”, “postgresql” etc.
last	integer	The time when the source was last heard from, as the number of seconds from 1 Jan 1970 UTC.
reporter	string	For sources of type other than “server”, this will be the name of the source whose agent is sending in the data for this source. Will be absent if type is “server”.

See the Standard Responses section for error responses.

Note that the JSON response body may not be pretty-printed as shown in the example.

Delete

curl -X POST \
  --data-binary @- \
  https://api.opsdash.com/v1/sources/delete <<EOBODY
{
  "apikey": "your-api-key",
  "name": "foobar"
}
EOBODY

import urllib2, json

data = json.dumps({
    'apikey': 'your-api-key',
    'name': 'foobar'
})
body = urllib2.urlopen('https://api.opsdash.com/v1/sources/delete', data)
response = json.load(body)

var request = require('request');

var options = {
  uri: 'https://api.opsdash.com/v1/sources/delete',
  method: 'POST',
  json: {
    'apikey': 'your-api-key',
    'name': 'foobar'
  }
};

request(options, function (error, response, body) {
  console.log(response.statusCode, body);
});

{}

Deletes a source and all associated data. The data is irrevocably deleted, and the operation cannot be undone. Use with care!

Request

POST https://api.opsdash.com/v1/sources/delete

Body

The request body must contain a valid JSON object with the following keys:

Key	Type	Description
apikey	string	Required. A valid API key from your Account Info page.
name	string	Required. The name of the source to be deleted.

Response

This API returns an empty JSON object on success.

See the Standard Responses section for error responses. Notably, it returns 4002 “bad input” if the source does not exist.

Webhook

OpsDash supports configuring webhooks that can receive real-time notifications. Currently, OpsDash supports webhooks for receiving alert notifications.

Alert Notifications

{
  "version": 1,
  "at": 1489907211,
  "breach": [
    {
      "dashid": 2,
      "dashname": "webhook-test-01",
      "graphid": 42,
      "graphname": "Load Average",
      "source": "webhook-test-01",
      "metric": "sys.os.loadavg",
      "combine": 0,
      "breachtype": "warnub",
      "value": 2.4,
      "threshold": 2
    }
  ],
  "down": [
    {
      "source": "webhook-test-02",
      "down": true,
      "last": 1489907031
    }
  ],
  "status": "1 down, 1 warning"
}

Webhook alert notifications are sent out whenever:

an alert threshold is breached
an alert threshold that was breached has cleared
a source is marked as down
a source that was marked as down has cleared (has come back up)

A single Webhook notification may carry one or more such events.

The HTTP requests made by OpsDash are:

posted to your URL via HTTP or HTTPS, versions HTTP/2 and HTTP/1.1 supported
the request method is POST
the body of the request will be a JSON object, see details below
the notification is considered successful if an HTTP response with code 200 is received within 3 seconds
if the request times out, it is retried upto 5 times, with a delay of 5 seconds between retries

Request

POST https://your/webhook/url

Headers

The following extra HTTP headers will be set in the request:

Header	Value	Description
Content-Type	application/json
X-Message-Version	1	the version of the JSON message schema, currently 1
User-Agent	OpsDash/1.0	the user-agent and version
Cache-Control	no-store

Body

The request body will contain a valid JSON object with the following keys:

Key	Type	Description
version	number	The message schema version, currently 1.
at	number	The time the notification was sent out, as the number of seconds from 1 Jan 1970 UTC.
breach	array	An array of “breach” objects, each representing a metric that has breached an upper/lower warning/critical threshold, or has cleared. See table below. May be absent.
down	array	An array of “down” objects, each representing a source that has just gone down, or has come up. See table below. May be absent.

Each “down” object has the following keys:

Key	Type	Description
source	string	The name of the source that has gone down or come up.
down	boolean	Will be true if the source has gone down, or false if the source has come up.
last	integer	The time when the source was last heard from, as the number of seconds from 1 Jan 1970 UTC.

Each “breach” object has the following keys:

Key	Type	Description
dashid	integer	Unique identifier of the dashboard which contains the graph with the breached metric.
dashname	string	The name of the dashboard. For system-generated dashboards, this will be the name of the source or sourcegroup.
graphid	integer	Unique identifier of the graph.
graphname	string	The title of the graph.
source	string	The source or the sourcegroup (see “combine” key below) involved in the breach.
metric	string	The metric involved in the breach.
combine	integer	If 0, then “source” is the name a source. If 1, then it is a sourcegroup, and the data series denotes the average. If 2, then it is a sourcegroup, and the data series denotes the sum.
breachtype	string	The type of breach that occured. Value is one of: “critlb”, “warnlb”, “warnub”, “critub” or an empty string, and indicates which threshold was breached. “lb” stands for lower bound, and “ub” for upper bound. If empty, the breach has cleared.
value	float	The value of the metric that exceeded the threshold.
threshold	float	The threshold, corresponding to the “breachtype”, that was set. This is valid only if “breachtype” is set.
status	string	A human-readable summary of the current overall alert status.

Note that the JSON request body may not be pretty-printed as shown in the example.

Response

The webhook must return an HTTP response with a status code of 200 within 3 seconds for the notification to be considered successful. No other parts of the response are examined.

Standard Responses

Generally, the OpsDash SaaS API will respond to requests with HTTP status code 200, 400 or 500. A status of 200 indicates success, 400 a client-side error and 500 a server-side error.

The body of the HTTP response will be a JSON object. In case of a success response, the JSON object can be empty (the body will be {}). If not empty, the object will have two properties, like so:

{ "code": 4003, "message": "bad timestamp" }

The code is an integer error code that provides a more specific identification of the error. message is a human-readable descriptive string for the error code.

The possible responses are:

Code	Message
4001	“malformed request body”
4002	“bad input”
4003	“bad timestamp”
4004	“project disabled”
4005	“bad api key”
5001	“internal error”

If the HTTP response code is 500, then we recommend that you retry the call after a delay.

Feedback

Your feedback about these APIs, as well as questions, suggestions and comments are welcome! Drop us a mail at api-team@rapidloop.com.