Introduction

Welcome to the API Science API documentation. Our API allows you to perform nearly all of the operations available in our web interface. In addition, some newer functionality is available only here in the API and not yet exposed in the web UI.

Please note that the API Science API is currently under active development and is possible that any information in this document is subject to change.

RESTful Style

The API Science API is designed to follow common RESTful API conventions. Most operations are performed using four HTTP methods: POST (create), GET (retrieve), PATCH (update), and DELETE (remove).

SSL Only

All requests to the API must use HTTPS. Any requests to a non-SSL endpoint will be redirected (via a 301 response) to the corresponding SSL endpoint.

Error Handling

All API calls return a corresponding HTTP response code and further details within the response payload. See the Errors section below for more details.

Dates

All date and time values are returned in Universal Time Coordinated (UTC) using ISO 8601 format.

Responses

Data Format

All data is returned as UTF-8 in JSON format. All resource requests support an optional path suffix of ‘.json’ which makes this explicit (ex: /monitors/2399948.json).

Common Response Structure

Response payloads have a common structure, with two required blocks of “meta” and “data”, and two optional sections of “pagination” and “error”.

   "meta": {
      "status": "success"
    }

The “meta” object always contains a “status” value and optionally contains additional elements depending on the type and result of API call made. See the Monitor Reporting() section for examples of additional data in “meta”.

Attribute	Description
status	string Either “success” or “failure”. Any HTTP 4xx-level response will return “error”.

See the Errors section below for more on the Error object.

"pagination": {
   "next": "https://api.apiscience.com/v1/monitors/23234881/checks?start=8436910&page=4&count=10",
   "previous": "https://api.apiscience.com/v1/monitors/23234881/checks?start=8436910&page=2&count=10",
   "first": "https://api.apiscience.com/v1/monitors/23234881/checks?start=8436910&page=1&count=10",
   "last": "https://api.apiscience.com/v1/monitors/23234881/checks?start=8436910&page=32&count=10"
}

The “pagination” object contains a set of links to allow navigation through a list of API results.

Attribute	Description
next	string URL address to retrieve the next “count” number of records in this list.
previous	string URL address to retrieve the previous “count” number of records in this list.
frist	string URL address to retrieve the first “count” number of records in this list.
last	string URL address to retrieve the last “count” number of records in this list.

For API calls that support paging, the following parameters can be supplied (note that when paging through resultes, you will commonly use the supplied URLs within the “pagination” object above):

Parameter	Description
start	integer Identifier of the first element of the result set.
page	integer Page number within the requested result set.
count	integer Number of records to be returned.

Authentication

API Keys

API Science uses API keys to control access to the API. Underneath Account Settings > API keys you can create and manage your API keys.

By default API keys have the same access controls as the user account they are bound to. In addition, any IP address may utilize the API key for access. If an IP address is input into the whitelist, the API key will be limited to only calls from that IP. Wildcards (*) are supported in the IP whitelist but currently only one IP address per key is supported.

Your API key must be included in all API requests to the server in an Authorization HTTP header formatted as:

Authorization: Bearer <YOUR_API_KEY>

You must replace <YOUR_API_KEY> with your account’s API key.

Roles

Note that API permissions are tied to the authorization level of your account. For example, if for a given monitor you have read-only access, then you have only those same corresponding read-only capabilities in the API.

Monitors

Introduction

Monitors are the building blocks of your tests. They are the logical unit that contains a web workflow that you want to test. A Monitor typically contains 1 or more Templates, each of which represents a single step (API call).

Attributes


{
  "id": 99823487,
  "name": "Monitor #1",
  "frequency": 1800,
  "active": true,
  "shared": false,
  "location": "Ireland",
  "tags": [
    "production",
    "mobile"
  ],
  "summary": {
    "status": "up",
    "performance": 646.80,
    "uptime": 99.12,
    "lastCheck": "2014-06-16T17:49:17.000Z"
  },
  "templates": [],
  "createdAt": "2014-06-16T17:49:17.000Z",
  "updatedAt": "2014-06-16T17:49:17.000Z"
}

Attribute	Description
id	integer The ID of the monitor.
name	string The name of the monitor.
frequency	integer The frequency, in seconds, that this monitor runs. Options are: 60, 300, 600, 900, 1800, 3600.
active	boolean This flag determines whether the monitor is either running or paused. When creating a new monitor, if this flag is set to true, the monitor will immediately begin monitoring. By default, this field is set to false.
shared	boolean Indicates if the monitor is one of the publicly available sample monitors that API Science provides.
location	string The location from which this monitor is run. One of: “Washington DC”, “Oregon”, “Ireland”.
tags	array of strings Any tags that have been applied to a monitor. Used for sorting, querying, and applying actions to groups of monitors.
summary	object status: The current state of the monitor. Options include: paused, pending, up, down performance: The average response time, in milliseconds, of the monitor over the last 24 hours. uptime: Uptime percentage over the last 24 hours. lastCheck: Time when the last check was made.
templates	array of objects A series of template objects associated with this monitor.
createdAt	timestamp Time when the monitor was created.
updatedAt	timestamp Time when the monitor was last updated.

Get All Monitors

curl 'https://api.apiscience.com/v1/monitors'
  -H 'Authorization: Bearer <YOUR_API_KEY>'

$.ajax({
  url: "https://api.apiscience.com/v1/monitors",
  headers: {
    "Authorization" : "Bearer <YOUR_API_KEY>"
  }
}).done(function(data) {
  console.log(data);
});

{
    "meta": {
        "status": "success",
        "numberOfResults": 2
    },
    "data": [
        {
            "id": 998832233,
            "name": "Monitor #1",
            "...": "..."
        },
        {
            "id": 19204332,
            "name": "Monitor #2",
            "...": "..."
        }
    ]
}

This endpoint retrieves a list of all your monitors.

HTTP Request

GET https://api.apiscience.com/v1/monitors

GET https://api.apiscience.com/v1/monitors?tags=foo&tags=bar

Parameter	Description
tags	Optionally filter monitors by tags. Can be chained multiple times to do an inclusive tag search.

Get a Specific Monitor

curl 'https://api.apiscience.com/v1/monitors/28874531'
  -H 'Authorization: Bearer <YOUR_API_KEY>'

$.ajax({
  url: "https://api.apiscience.com/v1/monitors/28874531",
  headers: {
    "Authorization" : "Bearer <YOUR_API_KEY>"
  }
}).done(function(data) {
  console.log(data);
});

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 28874531,
        "name": "Monitor #1",
        "frequency": 1800,
        "active": true,
        "createdAt": "2014-08-21T21:11:39.000Z",
        "updatedAt": "2014-08-21T21:11:39.000Z",
        "shared": false,
        "summary": {
            "status": "up",
            "performance": 0.0,
            "uptime": 0.0,
            "lastCheck": "2014-08-27T14:52:34.000Z"
        },
        "templates": [
            {
                "id": 34143289,
                "name": null,
                "method": "GET",
                "href": "https://www.apiscience.com",
                "headers": [],
                "params": [],
                "body": "",
                "postScript": "",
                "validations": [
                    {
                        "id": 34143289,
                        "kind": "Response Code",
                        "operator": "==",
                        "assertion": "500"
                    }
                ],
                "createdAt": "2014-08-21T21:11:39.000Z",
                "updatedAt": "2014-08-26T17:52:25.000Z"
            }
        ]
    }
}

This endpoint retrieves a specific monitor.

HTTP Request

GET https://api.apiscience.com/v1/monitors/<ID>

URL Parameters

Parameter	Description
ID	The ID of the monitor to retrieve

Creating Monitors

There are two primary ways you can create a monitor using our API: with and without a template. When you create a basic single-step monitor on the API Science website, you are creating both a monitor and a template together. With the API, you can choose whether you want to create them both with a single API call (see the convenience method below), or using a series of API calls. With the latter, you will typically create a single monitor (with no template) and then make one or more API calls to create individual templates associated with that monitor.

Create a Monitor

curl 'https://api.apiscience.com/v1/monitors'
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer s8uXOo5YHvkklvIEUoNC4A'
  --data-binary $'{ "name" : "Fullstack Monitor Test", "frequency" : 60, "location" : "eu" }'

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 28874531,
        "name": "Fullstack Monitor Test",
        "frequency": 3600,
        "active": false,
        "createdAt": "2014-09-05T20:51:46.617Z",
        "updatedAt": "2014-09-05T20:51:46.745Z",
        "shared": false,
        "summary": {
            "status": "pending",
            "performance": 0,
            "uptime": 0,
            "lastCheck": null
        },
        "templates": []
    }
}

This endpoint creates a monitor without a template.

HTTP Request

POST https://api.apiscience.com/monitors

Parameter	Description
name	required The name of the monitor.
frequency	required The frequency that you want this monitor to be run at. Options are: 60, 300, 600, 900, 1800, 3600 (in seconds).
active	This flag determines whether the monitor is either running or paused. When creating a new monitor, if this flag is set to true, the monitor will immediately begin monitoring. By default, this field is set to false.

Create a Monitor with a Template

curl 'https://api.apiscience.com/v1/monitors'
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer s8uXOo5YHvkklvIEUoNC4A'
  --data-binary $'{ "name" : "Fullstack Monitor Test", "frequency" : 60, "location" : "eu", "active" : false, "templates" : [ { "name" : "Fullstack Template Test", "href" : "http://apiscience.com", "method" : "POST", "headers" : [ { "Authorization" : "none" }, { "Authorization" : "oauth2" }, { "Dynamic" : "{{foobar}}" } ], "params" : [ { "foobar" : "cow" } ], "validators" : [ { "kind" : "regex", "assertion" : "foo" } ] } ] }'

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 28874531,
        "name": "Fullstack Monitor Test",
        "frequency": 3600,
        "active": false,
        "createdAt": "2014-09-03T00:42:18.335Z",
        "updatedAt": "2014-09-03T00:42:18.335Z",
        "shared": false,
        "status": {
            "status": "no_data",
            "performance": 0,
            "uptime": 0,
            "lastCheck": null
        },
        "templates": [
            {
                "id": 34143289,
                "name": "Fullstack Template Test",
                "method": "POST",
                "href": "http://apiscience.com",
                "headers": [
                    {
                        "Authorization": "none"
                    },
                    {
                        "Authorization": "oauth2"
                    },
                    {
                        "Dynamic": "{{foobar}}"
                    }
                ],
                "params": [
                    {
                        "foobar": "cow"
                    }
                ],
                "body": null,
                "postScript": null,
                "validations": [
                    {
                        "id": 34143289,
                        "kind": "Regex",
                        "assertion": "foo"
                    }
                ],
                "createdAt": "2014-09-03T00:42:18.000Z",
                "updatedAt": "2014-09-03T00:42:18.000Z"
            }
        ]
    }
}

This endpoint creates a monitor with a template.

The parameters to post are the same as creating a monitor above with the exception of also adding template objects to your JSON call. To create a multistep monitor, just add mutliple template objects into the templates array. Note that if you want a more granular step-by-step breakdown and diagnostics, you can do a single create monitor call and multiple template calls.

HTTP Request

POST https://api.apiscience.com/monitors

Parameter	Description
name	required The name of the monitor.
frequency	required The frequency that you want this monitor to be run at. Options are: 60, 300, 600, 900, 1800, 3600 (in seconds).
active	This flag determines whether the monitor is either running or paused. When creating a new monitor, if this flag is set to true, the monitor will immediately begin monitoring. By default, this field is set to false.
templates	An array of template objects to be created. These objects must be put into an array. If there is any issue creating a template or any of it’s nested items, the entire monitor creation will fail.

Testing your Monitor

curl 'https://api.apiscience.com/v1/monitors/395/test' -H 'Authorization: Bearer <YOUR_API_KEY>'

{
    "meta": {
        "status": "Success"
    },
    "data": {
        "id": 8347885,
        "href": "https://api.apiscience.com/v1/checks/8347885.json",
        "statistics": {
            "resolve": 1.35,
            "connect": 94.22,
            "transfer": 94.78,
            "closing": 0.08,
            "total": 190.43,
            "downloadSize": 184
        },
        "monitor": {
            "id": 28874531,
            "href": "https://api.apiscience.com/v1/monitors/395.json",
            "name": "Ultimate Test"
        },
        "calls": [
            {
                "id": 10038767,
                "template": {
                    "id": 34143289,
                    "href": "https://api.apiscience.com/v1/monitors/395/templates/1835.json",
                    "name": "Fullstack Template Test"
                },
                "statistics": {
                    "resolve": 1.35,
                    "connect": 94.22,
                    "transfer": 94.78,
                    "closing": 0.08,
                    "total": 190.43,
                    "downloadSize": 184
                },
                "request": {
                    "method": "POST",
                    "method": "http://apiscience.com",
                    "headers": null,
                    "body": null,
                    "params": null
                },
                "response": {
                    "contentType": "text/html",
                    "stausCode": 301,
                    "headers": [
                        {
                            "Server": "nginx/1.2.1"
                        },
                        {
                            "Date": "Sat, 13 Sep 2014 01:12:12 GMT"
                        },
                        {
                            "Content-Type": "text/html"
                        },
                        {
                            "Content-Length": "184"
                        },
                        {
                            "Connection": "keep-alive"
                        },
                        {
                            "Location": "http://www.apiscience.com/"
                        }
                    ],
                    "body": "<html>\r\n<head><title>301 Moved Permanently</title></head>\r\n<body bgcolor=\"white\">\r\n<center><h1>301 Moved Permanently</h1></center>\r\n<hr><center>nginx/1.2.1</center>\r\n</body>\r\n</html>\r\n"
                },
                "validationFailures": [
                    {
                        "kind": "Regex",
                        "message": "Response does not contain any regex matchs for '~/foo/'"
                    }
                ],
                "createdAt": "2014-09-13T01:12:11.000Z",
                "updatedAt": "2014-09-13T01:13:28.000Z"
            },
            {
                "id": 10038768,
                "template": {
                    "id": 34143289,
                    "href": "https://api.apiscience.com/v1/monitors/395/templates/1836.json",
                    "name": null
                },
                "statistics": {
                    "resolve": 444.53,
                    "connect": 75748.27,
                    "transfer": 29.6,
                    "closing": 0,
                    "total": 76222.4,
                    "downloadSize": 219
                },
                "request": {
                    "method": "GET",
                    "href": "http://google.com",
                    "headers": [],
                    "body": "",
                    "params": []
                },
                "response": {
                    "contentType": "text/html; charset=UTF-8",
                    "stausCode": 301,
                    "headers": [
                        {
                            "Location": "http://www.google.com/"
                        },
                        {
                            "Content-Type": "text/html; charset=UTF-8"
                        },
                        {
                            "Date": "Sat, 13 Sep 2014 01:13:28 GMT"
                        },
                        {
                            "Expires": "Mon, 13 Oct 2014 01:13:28 GMT"
                        },
                        {
                            "Cache-Control": "public, max-age=2592000"
                        },
                        {
                            "Server": "gws"
                        },
                        {
                            "Content-Length": "219"
                        },
                        {
                            "X-XSS-Protection": "1; mode=block"
                        },
                        {
                            "X-Frame-Options": "SAMEORIGIN"
                        },
                        {
                            "Alternate-Protocol": "80:quic,p=0.002"
                        }
                    ],
                    "body": "<HTML><HEAD><meta http-equiv=\"content-type\" content=\"text/html;charset=utf-8\">\n<TITLE>301 Moved</TITLE></HEAD><BODY>\n<H1>301 Moved</H1>\nThe document has moved\n<A HREF=\"http://www.google.com/\">here</A>.\r\n</BODY></HTML>\r\n"
                },
                "validationFailures": [],
                "createdAt": "2014-09-13T01:13:28.000Z",
                "updatedAt": "2014-09-13T01:13:28.000Z"
            }
        ],
        "createdAt": "2014-09-13T01:13:28.000Z",
        "updatedAt": "2014-09-13T01:13:28.000Z"
    }
}

If you need to test that your monitor is working, you can hit this endpoint to see the results of a single run of your monitor in it’s current. This is only a temporary record and will not effect your monitor’s history or status periods.

GET https://api.apiscience.com/monitors/<monitor_id>/test

Parameter	Description
(none)

Apply Actions to Multiple Monitors

curl 'https://api.apiscience.com/v1/monitors?tags=mew' -X PATCH -H 'Content-Type: application/json' -H 'Authorization: Bearer 3oyi6VL7R0YkenECoNj6Ow --data-binary '{ "active" : false }'

{
    "meta": {
        "status": "success",
        "numberOfResults": 2
    },
    "data": [
        {
            "id": 28874531,
            "name": "Monitor #1",
            "frequency": 1800,
            "active": false,
            "createdAt": "2014-06-16T17:49:17.000Z",
            "updatedAt": "2014-06-16T17:49:17.000Z",
            "shared": false,
            "status": {
                "status": "not_run",
                "performance": 0.0,
                "uptime": 0.0,
                "lastCheck": "2014-06-16T17:49:17.000Z"
            },
            "templates": [
            ]
        },
        {
            "id": 34143289,
            "name": "Monitor #2",
            "frequency": 3600,
            "active": false,
            "createdAt": "2014-07-25T16:22:30.000Z",
            "updatedAt": "2014-07-25T16:22:30.000Z",
            "shared": false,
            "status": {
                "status": "active",
                "performance": 0.0,
                "uptime": 0.0,
                "lastCheck": "2014-08-07T01:30:41.000Z"
            },
            "templates": [
                {
                    "id": 34143289,
                    "name": null,
                    "method": "GET",
                    "href": "http://www.google.com",
                    "headers": [],
                    "params": [],
                    "body": "",
                    "postScript": "",
                    "createdAt": "2014-07-25T16:22:30.000Z",
                    "updatedAt": "2014-08-18T19:08:16.000Z"
                }
            ]
        },
        ...
    ]

Used to apply changes to multiple monitors at once. Any of the monitor attributes can be mass changed wtih such as active, frequency, tags, ect.

PATCH https://api.apiscience.com/v1/monitors

PATCH https://api.apiscience.com/v1/monitors?tags=foo&tags=bar

Parameter	Description
tags	Optionally filter monitors by tags. Can be chained multiple times to do an inclusive tag search.

Templates

Introduction

Templates represent a single URL request.

Attributes

{
  "id": 34143289,
  "name": "Fullstack Template Test",
  "method": "POST",
  "href": "https://www.apiscience.com",
  "headers": [
    { "Authorization": "none" },
    { "Authorization": "oauth2" },
    { "Dynamic": "{{foobar}}" }
  ],
  "urlParameters": [
    { "foobar": "cow" }
  ],
  "body": null,
  "preProcessScript": null,
  "followRedirects": false,
  "validations": [],
  "createdAt": "2014-09-03T00:42:18.000Z",
  "updatedAt": "2014-09-03T00:42:18.000Z"
}

Attribute	Description
id	integer The ID of the template.
name	string The name of the template.
method	string The HTTP action to access the given URL. Options are: GET, POST, PUT, PATCH, DELETE.
url	string The URL to be accessed.
headers	array of key/values An array of key/value pairs to send as HTTP headers.
urlParameters	array of key/values An array of key/value pairs to send as URL parameters. These will be URL encoded. If you have provided parameters as part of the base URL these will be appended to those existing parameters.
body	string Raw body to be send with the request. Note that no encoding is performed on this data.
preProcessScript	string JavaScript to be executed prior to running this template. In the context of a multi-step monitor, the results of the previous call are available to this JavaScript context (ex: thus enabling you to extract and use data or variables from previous step prior to running this step).
validations	array of objects An array of validation objects to be run on the results of this template.
followRedirects	boolean True if this call should automatically follow HTTP redirects (default is False).
createdAt	timestamp Time when the template was created at.
updatedAt	timestamp Time when the template was last updated at.

Show a Monitor’s Templates

Gets a list of the templates associated with a monitor.

curl 'https://api.apiscience.com/v1/monitors/34143289/templates' -H 'Authorization: Bearer <YOUR_API_KEY>'

{
    "meta": {
        "status": "success",
        "count": 2
    },
    "data": [
        {
            "id": 1823235,
            "href": "https://api.apiscience.com/v1/monitors/34143289/templates/1823235.json",
            "name": "Fullstack Template Test",
            "method": "POST",
            "href": "http://apiscience.com",
            "headers": [],
            "urlParameters": [],
            "body": null,
            "preProcessScript": null,
            "validations": [
                {
                    "id": 34143289,
                    "kind": "Regex",
                    "assertion": "foo"
                }
            ],
            "createdAt": "2014-09-12T21:09:03.000Z",
            "updatedAt": "2014-09-12T21:09:03.000Z"
        },
        {
            "id": 1823236,
            "href": "https://api.apiscience.com/v1/monitors/34143289/templates/1823236.json",
            "name": null,
            "method": "GET",
            "href": "http://google.com",
            "headers": [],
            "urlParameters": [],
            "body": "",
            "preProcessScript": "",
            "validations": [],
            "createdAt": "2014-09-12T22:07:49.000Z",
            "updatedAt": "2014-09-12T22:07:49.000Z"
        }
    ]
}

GET https://api.apiscience.com/v1/monitors/<monitor_id>/templates

Parameter	Description
(none)

Get a Template

curl 'https://api.apiscience.com/v1/monitors/34143289/templates/8897123' -H 'Authorization: Bearer <YOUR_API_KEY>'

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 34143289,
        "href": "https://api.apiscience.com/v1/monitors/34143289/templates/8897123.json",
        "name": "Fullstack Template Test",
        "method": "POST",
        "href": "https://api.apiscience.com/",
        "headers": [],
        "urlParameters": [],
        "body": null,
        "preProcessScript": null,
        "validations": [
            {
                "id": 87845421,
                "kind": "Regex",
                "assertion": "foo"
            }
        ],
        "createdAt": "2014-09-12T21:09:03.000Z",
        "updatedAt": "2014-09-12T21:09:03.000Z"
    }
}

Used to retrieve a single template.

GET https://api.apiscience.com/v1/monitors/<monitor_id>/templates

Parameter	Description
(none)

Create a Template

curl 'https://api.apiscience.com/v1/monitors/1922876/templates' -H 'Content-Type: application/json' -H 'Authorization: Bearer <YOUR_API_KEY>' --data-binary $'{\n  "name": "My Cool Template",\n  "method": "POST",\n  "href": "http://apiscience.com",\n  "headers": [\n    { "Authorization": "none" },\n    { "Authorization": "oauth2" },\n    { "Dynamic": "{{foobar}}" }\n  ],\n  "urlParameters": [\n    { "foobar": "cow" }\n  ],\n  "body": null,\n  "preProcessScript": null,\n  "validations": []\n}\n'

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 87845421,
        "href": "https://api.apiscience.com/v1/monitors/1922876/templates/183985.json",
        "name": "Fullstack Template Test",
        "method": "POST",
        "href": "http://apiscience.com",
        "headers": [],
        "urlParameters": [],
        "body": null,
        "preProcessScript": null,
        "followRedirects" : false,
        "validations": [
            {
                "id": 17845321,
                "kind": "Regex",
                "assertion": "foo"
            }
        ],
        "createdAt": "2014-09-12T21:09:03.000Z",
        "updatedAt": "2014-09-12T21:09:03.000Z"
    }
}

Adds a new template to an existing monitor. This template will be added as the furthest step on a monitor, being the last template to be run in a multistep monitor.

POST https://api.apiscience.com/v1/monitors/<monitor_id>/templates

Parameter	Description
name	The name of the template.
method	required The HTTP action to access the given URL. Options are: GET, POST, PUTS, PATCH, DELETE.
url	required The URL to be accessed.
headers	An array of key/value pairs to send as headers.
urlParameters	array of key/values An array of key/value pairs to send as URL parameters. These will be URL encoded. If you have provided parameters as part of the base URL these will be appended to those existing parameters.
body	Raw body to be send with the request.
preProcessScript	string JavaScript to be executed prior to running this template. In the context of a multi-step monitor, the results of the previous call are available to this JavaScript context (ex: thus enabling you to extract and use data or variables from previous step prior to running this step).
validations	An array of validation objects to be run on the results of this template.
followRedirects	boolean True if this call should automatically follow HTTP redirects (default is False).

Checks

Introduction

Checks represent a single run of your monitor. They contain detailed information about the actual API calls that took place.

Attributes


{ 
  "href": "http://api.apiscience.com/v1/checks/8438120.json",
  "status": "success",
  "statistics": {
    "resolve": 65.15,
    "connect": 9.09,
    "processing": 10.09,
    "transfer": 0.05,
    "total": 84.39,
    "downloadSize": 0
  },
  "monitor": {
    "id": 187722,
    "href": "http://api.apiscience.com/v1/monitors/187722.json",
    "name": "Exploder"
  },
  "calls": [],
  "createdAt": "2015-02-05T22:21:22.000Z",
  "updatedAt": "2015-02-05T22:21:22.000Z"
}

Parameter	Description
href	url The URL identifier for this check.
status	string Represents whether all the calls in the check succeeded or not. Will either be “success” or “failure”.
statistics	object resolve: Amount of time to resolve the DNS. connect: Amount of time required to connect to the server. processing: Amount of time it took between server connection and first byte of data. transfer: The amount of time it took to send the full response. total: Total amount of time the check took. downloadSize: Size of the transfer in kilobytes. (All times are in milliseconds.)
monitor	object A reference to the monitor that ran the check and its name.
calls	array of objects A series of call objects associated with this check.
createdAt	timestamp Time when the check was created at.
updatedAt	timestamp Time when the check was last updated at.

Get Checks For A Monitor

curl 'https://api.apiscience.com/v1/monitors/187722/checks.json' -H 'Authorization: Bearer <YOUR_API_KEY>'

From a monitor endpoint, you can recieve the last 20 checks for that monitor by appending /checks.json to the monitors endpoint.

{
    "meta": {
        "status": "success",
        "numberOfResults": 20
    },
    "data": [],
    "pagination": {
        "next": "https://api.apiscience.com/v1/monitors/187722/checks.json?start=8435526&count=20"
    }
}

URL Parameters

Parameter	Description
start	integer The start number represents which ID is the maximum check that could be found. Its purpose is to root the pagination even as new data keeps on being continually added. Typically this will be generated by the provided pagination URL and not something the user needs to create.
count	integer The number of checks to return.

Monitor Tags

Introduction

Tags are optional, user-defined labels that can be associated with any Monitor. Tags allow the sorting, grouping, and running of mass actions on monitors. Each monitor can have any number of tags.

List All Tags

curl 'https://api.apiscience.com/v1/tags' -H 'Authorization: Bearer <YOU_API_KEY>'

{
    "meta": {
        "status": "success",
        "numberOfResults": 4
    },
    "data": [
        "foo",
        "bar",
        "cat",
        "kitten"
    ]
}

Returns a list of tags currently used by your account.

Detailed List All Tags

curl 'https://api.apiscience.com/v1/tags?detailed=1' -H 'Authorization: Bearer <YOU_API_KEY>'

{
    "meta": {
        "status": "success",
        "numberOfResults": 4
    },
    "data": {
        "foo": [
            "https://api.apiscience.com/v1/monitors/245.json"
        ],
        "bar": [
            "https://api.apiscience.com/v1/monitors/245.json",
            "https://api.apiscience.com/v1/monitors/183.json"
        ],
        "cat": [
            "https://api.apiscience.com/v1/monitors/183.json"
        ],
        "kitten": [
            "https://api.apiscience.com/v1/monitors/183.json"
        ]
    }
}

Returns a list of tags with links to each monitor using that tag.

Create a Tag

curl 'https://api.apiscience.com/v1/monitors/23393339' 
  -X PATCH
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer s8uXOo5YHvkklvIEUoNC4A'
  --data-binary $'{ "tags" : [ "foo", "bar" ] }'

{
    "meta": {
        "status": "success"
    },
    "data": [
        "foo",
        "bar",
    }
}

Monitor tags can be added either during the creation of the monitor itself or separately by using a PATCH method call to update an existing monitor. To PATCH an existing monitor use the following:

HTTP Request

PATCH https://api.apiscience.com/v1/monitors/<ID>.json

Parameter	Description
tags	A JSON array of strings.

Contacts

Introduction

When a monitor runs and one or more of its validations fail, API Science will attempt to reach any Contacts you have linked to that validation rule. Currently supported contact types include:

Email: An email alert is sent to a specified address. This address can be a group alias.
URL: A webhook callback is made to the specified URL. See webhooks section below for more.
PagerDuty: A callback is made to PageDuty.

Note that adding URL and PagerDuty contacts is currently supported via the API only.

Attributes


{
    "id": 282744475,
    "label": "John Smith",
    "type": "email",
    "value": "jsmith@example.org",
    "createdAt": "2015-02-05T21:16:33.000Z",
    "updatedAt": "2015-02-05T21:16:33.000Z"
}

Parameter	Description
id	integer The ID of the contact.
label	string User-defined label for this contact.
type	string Type of contact, options are: “email”, “url”, “pagerduty”.
value	string Contents of value vary based on the “type” of contact being created: an email address, a URL or your PagerDuty API key.
createdAt	timestamp Time when the contact was created.
updatedAt	timestamp Time when the contact was last updated.

Get All Contacts

curl 'https://api.apiscience.com/v1/contacts.json'
  -H 'Authorization: Bearer <YOUR_API_KEY>'

$.ajax({
  url: "https://api.apiscience.com/v1/contacts.json",
  headers: {
    "Authorization" : "Bearer <YOUR_API_KEY>"
  }
}).done(function(data) {
  console.log(data);
});

{
    "meta": {
        "status": "success",
        "numberOfResults": 2
    },
    "data": [
        {
            "id": 998832233,
            "label": "John Smith",
            "...": "..."
        },
        {
            "id": 19204332,
            "label": "PagerDuty callback",
            "...": "..."
        }
    ]
}

This endpoint retrieves a list of all your contacts.

HTTP Request

GET https://api.apiscience.com/v1/contacts.json

Get a Specific Contact

curl 'https://api.apiscience.com/v1/contacts/293384334.json'
  -H 'Authorization: Bearer <YOUR_API_KEY>'

$.ajax({
  url: "https://api.apiscience.com/v1/contacts/293384334.json",
  headers: {
    "Authorization" : "Bearer <YOUR_API_KEY>"
  }
}).done(function(data) {
  console.log(data);
});

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 293384334,
        "label": "John Smith",
        "type": "email",
        "value": "jsmith@example.org",
        "createdAt": "2015-02-05T21:16:33.000Z",
        "updatedAt": "2015-02-05T21:16:33.000Z"
    }
}

This endpoint retrieves a specific contact.

HTTP Request

GET https://api.apiscience.com/v1/contacts/<ID>.json

URL Parameters

Parameter	Description
ID	The ID of the contact to retrieve

Create a Contact

curl 'https://api.apiscience.com/v1/contacts.json'
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer s8uXOo5YHvkklvIEUoNC4A'
  --data-binary $'{ "label": "John Smith", "type": "email", "value": "jsmith@example.org" }'

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 282744475,
        "label": "John Smith",
        "type": "email",
        "value": "jsmith@example.org",
        "createdAt": "2015-02-05T21:16:33.000Z",
        "updatedAt": "2015-02-05T21:16:33.000Z"
    }
}

This endpoint creates a contact.

HTTP Request

POST https://api.apiscience.com/contacts.json

Parameter	Description
label	User-defined label for this contact.
type	required Type of contact, options are: “email”, “url”, “pagerduty”.
value	required Contents of value vary based on the “type” of contact being created: an email address, a URL or your PagerDuty API key.

Update a Contact

curl 'https://api.apiscience.com/v1/contacts/293384334.json'
  -X PATCH
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer s8uXOo5YHvkklvIEUoNC4A'
  --data-binary $'{ "label": "Jane Smith" }'

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": 293384334,
        "label": "Jane Smith",
        "type": "email",
        "value": "jsmith@example.org",
        "createdAt": "2015-02-05T21:16:33.000Z",
        "updatedAt": "2015-02-05T21:16:33.000Z"
    }
}

This endpoint updates a contact.

HTTP Request

PATCH https://api.apiscience.com/v1/contacts/<ID>.json

Where is the “id” of the contact to be updated.

Parameter	Description
label	User-defined label for this contact.
type	Type of contact, options are: “email”, “url”, “pagerduty”.
value	Contents of value vary based on the “type” of contact being created: an email address, a URL or your PagerDuty API key.

Delete a Contact

curl 'https://api.apiscience.com/v1/contacts/293384334.json'
  -X DELETE
  -H 'Authorization: Bearer s8uXOo5YHvkklvIEUoNC4A'

{
    "meta": {
        "status": "success"
    }
}

This endpoint deletes a contact.

HTTP Request

DELETE https://api.apiscience.com/v1/contacts/<ID>.json

Where is the “id” of the contact to be updated.

Monitor Reports

Reporting APIs

API Science provides a set of convenience APIs designed to assist in creating commonly needed report data. Each supports a set of query parameters to help specify constraints such as how much data to return (ex: date range) as well as roll-up intervals (ex: hourly or daily).

In addition to returning the requested report data, responses to this set of calls also includes additional information in the “meta” object of the response.

"meta": {
  "status": "success",
  "numberOfResults": 24,
  "resolution": "hour",
  "startPeriod": "2014-09-01T18:00:00Z",
  "endPeriod": "2014-09-02T19:00:00Z"
}

Attribute	Description
numberOfResults	integer Total count of results to the given query.
resolution	string The roll-up resolution for any aggregated data in this report: “hour”, “day”, or “week”.
startPeriod	date The date of the earliest entry in this report.
endPeriod	date The date of the latest entry in this report.

Due to how data is collected by API Science during states when a monitor is paused, there are two cases where data generated by the reporting API may look weird:

[Uptime]
During rollup calculations for uptime, if there are paused states for a monitor they are ignored in the calculation. Only if the the entire section of the rollup is paused will it result in null instead of calculating an uptime percentage. In the extereme, for an hour roll up, if 59 minutes are paused and 1 minute was at 100% uptime, the performance for that rollup would still be 100%.

[Performance]
Similar to uptime, performance data is collected when test are manually ran during a paused state. They will be used in a rollup calculation and appear as a spike of data even if the monitor was paused during that period.

Performance Report

curl 'https://api.apiscience.com/v1/monitors/<ID>/performance?start=2014-09-01&end=2014-09-02&resolution=hour' 
  -H 'Authorization: Bearer <YOUR_API_KEY>'

{
    "meta": {
        "status": "success",
        "numberOfResults": 24,
        "resolution": "hour",
        "startPeriod": "2014-09-01T18:00:00Z",
        "endPeriod": "2014-09-02T19:00:00Z"
    },
    "data": [
        {
            "averageResolve": 2.53,
            "averageConnect": 83.73,
            "averageTransfer": 415.84,
            "averageClosing": 480.71,
            "averageTotal": 982.83,
            "startPeriod": "2014-09-02T18:00:00Z",
            "endPeriod": "2014-09-02T19:00:00Z"
        },
        {
            "averageResolve": 2.46,
            "averageConnect": 85.81,
            "averageTransfer": 399.07,
            "averageClosing": 462.27,
            "averageTotal": 949.62,
            "startPeriod": "2014-09-02T17:00:00Z",
            "endPeriod": "2014-09-02T18:00:00Z"
        },
        ...
    ]
}

This endpoint returns a performance report for a given monitor. It can be provided a start time, end time, and resolution to create a custom report or may be passed one of our presets to generate a report.

HTTP Request

GET https://api.apiscience.com/v1/monitors/<ID>/performance.json?preset=lastDay

GET https://api.apiscience.com/v1/monitors/<ID>/performance.json?start=2014-09-01&end=2014-09-02&resolution=hour

Parameter	Description
start	required The start point you want to build a performance report from. Format should be in ISO 8601. If the timezone is not provided, the report will assume UTC. Partial dates (ex: YYYY-MM-DD) are supported.
end	required The end point you want to build a performance report from. Format should be in ISO 8601. If the timezone is not provided, the report will assume UTC. Partial dates (ex: YYYY-MM-DD) are supported
resolution	requred The resolution is the time unit for aggregating data, with allowable values of “hour”, “day”, and “week”.
preset	Present for commonly requested reports. Options are “lastDay” and “lastWeek”.

Uptime Report

curl 'https://api.apiscience.com/v1/monitors/<ID>/uptime.json?preset=lastDay'
  -H 'Authorization: Bearer <YOU_API_KEY>'

{
    "meta": {
        "status": "success",
        "numberOfResults": 24,
        "resolution": "hour",
        "startPeriod": "2014-09-04T19:38:36.842Z",
        "endPeriod": "2014-09-05T12:38:36-07:00"
    },
    "data": [
        {
            "uptime": 1,
            "startPeriod": "2014-09-05T18:38:36.762Z",
            "endPeriod": "2014-09-05T12:38:36-07:00"
        },
        {
            "uptime": 1,
            "startPeriod": "2014-09-05T17:38:36.765Z",
            "endPeriod": "2014-09-05T18:38:36.765Z"
        },
        ...
    ]
}

This endpoint returns an uptime report for a given monitor.

HTTP Request

GET https://api.apiscience.com/v1/monitors/<id>/uptime.json?preset=lastWeek

GET https://api.apiscience.com/v1/monitors/<id>/uptime.json?start=2014-09-01&end=2014-09-02&resolution=hour

Parameter	Description
start	required The start point you want to build a performance report from. Format should be in ISO 8601. If the timezone is not provided, the report will assume UTC. Partial dates (ex: YYYY-MM-DD) are supported.
end	required The end point you want to build a performance report from. Format should be in ISO 8601. If the timezone is not provided, the report will assume UTC. Partial dates (ex: YYYY-MM-DD) are supported
resolution	requred The resolution is the time unit for aggregating data, with allowable values of “hourly”, “daily”, and “weekly”.
preset	Present for commonly requested reports. Options are “lastDay” and “lastWeek”.

Errors

Overview

The API Science API returns success/failure status for each call in two ways: using the HTTP response code and within the body of the response payload. If a call is successful an HTTP 200 is returned and the “meta” block contains a value of “status”:“success”. For any error response in the 4xx or 5xx range, the response “meta” block contains “status”:“error” and an “error” block contains further details on the error.

Error Object

Any API call that results in a 4xx-level error will contain an additional “error” object with further details on the issue.

Attributes

{
    "code": 401,
    "name": "Unauthorized",
    "message": "Invalid or missing API key",
    "infoUrl": "https://developer.apiscience.com/#error-reference"
}

Parameter	Description
code	integer The HTTP response code.
name	string Short identifier for this error.
message	string More detailed description of the error.
infoUrl	string A URL which can be used to obtain more information on the likely cause of this error.

Error Reference

The API uses the following HTTP response codes to indicate the success or failure of each API call:

HTTP Code	Meaning
200	OK – Request successful
201	Created – Successfully created this resource
301	Redirect – The requested resource is available at another address
400	Bad Request – Improperly formatted request (ex: invalid or missing parameters)
401	Unauthorized – API key is invalid or missing
403	Forbidden – Your API permission level does not allow access to the requested resource
404	Not Found – The specified resource could not be found
500	Internal Server Error – We had a problem with our server (and team has been notified)