NAV
Shell JavaScript

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”.

Here is a typical “meta” object returned from an API call requesting a list of items

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

Here is a typical “pagination” object returned from an API call requesting a list of items

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

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);
});

The above command returns JSON like this, with “data” containing an array of Monitor objects:

{
    "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);
});

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

{
    "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" } ] } ] }'

The above command returns JSON structured like this:

{
    "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>'

The above command returns a check JSON object structored like this:

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

The above command returns a series of monitor JSON object JSON objects structured like this:

{
    "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>'

Returns a list of template JSON objects structured like this:

{
    "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>'

Returns a single template JSON object structured like this:

{
    "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'

Returns a single template JSON object structured like this:

{
    "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>'

The above command returns JSON structured like this:

{
    "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>'

The above command returns JSON structured like this:

{
    "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" ] }'

The above command returns JSON structured like this:

{
    "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:

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);
});

The above command returns JSON like this, with “data” containing an array of Contact objects:

{
    "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);
});

The above command returns JSON structured like this:

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


The above command returns JSON structured like this:

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


The above command returns JSON structured like this:

{
    "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'


The above command returns JSON structured like this:

{
    "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.

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>'

The above command returns JSON structured like this:

{
    "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>'

The above command returns JSON structured like this:

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

Here is a sample “error” object for a 401 response:

{
    "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)