{% extends "front/base_docs.html" %} {% load compress staticfiles hc_extras %} {% block title %}REST API - {% site_name %}{% endblock %} {% block description %} {% endblock %} {% block docs_content %}

REST API

{% site_name %} REST API supports listing, creating, updating, pausing and deleting checks in user's account.

API Endpoints

Get list of existing checks GET {{ SITE_ROOT }}/api/v1/checks/
Create a new check POST {{ SITE_ROOT }}/api/v1/checks/
Update an existing check POST {{ SITE_ROOT }}/api/v1/checks/<code>
Pause monitoring of a check POST {{ SITE_ROOT }}/api/v1/checks/<code>/pause
Delete check DELETE {{ SITE_ROOT }}/api/v1/checks/<code>

Authentication

Your requests to {% site_name %} REST API must authenticate using an API key. By default, an user account on {% site_name %} doesn't have an API key. You can create one in the Settings page.

The client can authenticate itself by sending an appropriate HTTP request header. The header's name should be X-Api-Key and its value should be your API key.

Alternatively, for POST requests with a JSON request body, the client can include an api_key field in the JSON document. See below the "Create a check" section for an example.

API Requests

For POST requests, the {% site_name %} API expects request body to be a JSON document (not a multipart/form-data encoded form data).

API Responses

{% site_name %} uses HTTP status codes wherever possible. In general, 2xx class indicates success, 4xx indicates an client error, and 5xx indicates a server error.

The response may contain a JSON document with additional data.

Get List of Existing Checks
GET {{ SITE_ROOT }}/api/v1/checks/

Returns a list of checks belonging to the user, optionally filtered by one or more tags.

Query String Parameters

tag=<value>

Filters the checks, and returns only the checks that are tagged with the specified value.

This parameter can be repeated multiple times.

Example:

{{ SITE_ROOT }}/api/v1/checks/?tag=foo&tag=bar

Example Request

{% include "front/snippets/list_checks_request.html" %}

Example Response

{% include "front/snippets/list_checks_response.html" %}

Create a Check
POST {{ SITE_ROOT }}/api/v1/checks/

Creates a new check and returns its ping URL. All request parameters are optional and will use their default values if omitted.

This API call can be used to create both "simple" and "cron" checks. To create a "simple" check, specify the "timeout" parameter. To create a "cron" check, specify the "schedule" and "tz" parameters.

Request Parameters

name

string, optional, default value: ""

Name for the new check.
tags

string, optional, default value: ""

A space-delimited list of tags for the new check.

Example:

{"tags": "reports staging"}
timeout

number, optional, default value: {{ default_timeout }}.

A number of seconds, the expected period of this check.

Minimum: 60 (one minute), maximum: 2592000 (30 days).

Example for 5 minute timeout:

{"kind": "simple", "timeout": 300}
grace

number, optional, default value: {{ default_grace }}.

A number of seconds, the grace period for this check.

Minimum: 60 (one minute), maximum: 2592000 (30 days).
schedule

string, optional, default value: "* * * * *".

A cron expression defining this check's schedule.

If you specify both "timeout" and "schedule" parameters, "timeout" will be ignored and "schedule" will be used.

Example for a check running every half-hour:

{"schedule": "0,30 * * * *"}
tz

string, optional, default value: "UTC".

Server's timezone. This setting only has effect in combination with the "schedule" paremeter.

Example:

{"tz": "Europe/Riga"}
channels

string, optional, default value: ""

By default, if a check is created through API, no notification channels are assigned to it. So, when the check goes up or down, no notifications would be sent. Set this field to a special value "*" to automatically assign all existing notification channels.
unique

array of string values, optional, default value: [].

Before creating a check, look for existing checks, filtered by fields listed in unique. If a matching check is found, return it with HTTP status code 200. If no matching check is found, proceed as normal: create a check and return it with HTTP status code 201.

The accepted values are: name, tags, timeout and grace.

Example:

{"name": "Backups", unique: ["name"]}

In this example, if a check named "Backups" exists, it will be returned. Otherwise, a new check will be created and returned.

Response Codes

201 Created Returned if the check was successfully created.
200 OK Returned if the unique parameter was used and an existing check was matched.
403 Forbidden Returned if the account's check limit has been reached. For free accounts, the limit is 20 checks per account.

Example Request

{% include "front/snippets/create_check_request_a.html" %}

Or, alternatively:

{% include "front/snippets/create_check_request_b.html" %}

Example Response

{% include "front/snippets/create_check_response.html" %}

Update an Existing Check
POST {{ SITE_ROOT }}/api/v1/checks/<code>

Updates an existing check. All request parameters are optional. The check is updated only with the supplied request parameters. If any parameter is omitted, its value is left unchanged.

Request Parameters

name

string, optional.

Name for the check.
tags

string, optional.

A space-delimited list of tags for the check.

Example:

{"tags": "reports staging"}
timeout

number, optional.

A number of seconds, the expected period of this check.

Minimum: 60 (one minute), maximum: 2592000 (30 days).

Example for 5 minute timeout:

{"kind": "simple", "timeout": 300}
grace

number, optional.

A number of seconds, the grace period for this check.

Minimum: 60 (one minute), maximum: 2592000 (30 days).
schedule

string, optional.

A cron expression defining this check's schedule.

If you specify both "timeout" and "schedule" parameters, "timeout" will be ignored and "schedule" will be used.

Example for a check running every half-hour:

{"schedule": "0,30 * * * *"}
tz

string, optional.

Server's timezone. This setting only has effect in combination with the "schedule" paremeter.

Example:

{"tz": "Europe/Riga"}
channels

string, optional.

Set this field to a special value "*" to automatically assign all existing notification channels.

Set this field to a special value "" (empty string) to automatically unassign all notification channels.

Response Codes

200 OK Returned if the check was successfully updated.

Example Request

{% include "front/snippets/update_check_request_a.html" %}

Or, alternatively:

{% include "front/snippets/update_check_request_b.html" %}

Example Response

{% include "front/snippets/create_check_response.html" %}

Pause Monitoring of a Check
POST {{ SITE_ROOT }}/api/v1/checks/<uuid>/pause

Disables monitoring for a check, without removing it. The check goes into a "paused" state. You can resume monitoring of the check by pinging it.

This API call has no request parameters.

Example Request

{% include "front/snippets/pause_check_request.html" %}

Note: the --data "" argument forces curl to send a Content-Length request header even though the request body is empty. For HTTP POST requests, the Content-Length header is sometimes required by some network proxies and web servers.

Example Response

{% include "front/snippets/pause_check_response.html" %}

Delete Check
DELETE {{ SITE_ROOT }}/api/v1/checks/<uuid>

Permanently deletes the check from user's account. Returns JSON representation of the check that was just deleted.

This API call has no request parameters.

Example Request

{% include "front/snippets/delete_check_request.html" %}

Example Response

{% include "front/snippets/create_check_response.html" %} {% endblock %} {% block scripts %} {% compress js %} {% endcompress %} {% endblock %}