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