API Reference
VCU TS Healthchecks REST API supports listing, creating, updating, pausing and deleting checks in user's account.
API Endpoints
Get a list of existing checks | GET https://healthcheck.ts.vcu.edu/api/v1/checks/ |
Create a new check | POST https://healthcheck.ts.vcu.edu/api/v1/checks/ |
Update an existing check | POST https://healthcheck.ts.vcu.edu/api/v1/checks/<code> |
Pause monitoring of a check | POST https://healthcheck.ts.vcu.edu/api/v1/checks/<code>/pause |
Delete check | DELETE https://healthcheck.ts.vcu.edu/api/v1/checks/<code> |
Get a list of existing integrations | GET https://healthcheck.ts.vcu.edu/api/v1/channels/ |
Authentication
Your requests to VCU TS Healthchecks REST API must authenticate using anAPI key. Each project in your VCU TS Healthchecks account has separate API keys.There are no account-wide API keys. By default, a project on VCU TS Healthchecks doesn't havean API key. You can create read-write and read-only API keys in theProject Settings page.
Regular API keys | Have full access to all documented API endpoints. |
Read-only API keys | Only work with the Get a list of existing checks endpoint. Some fields are omitted from the API responses. |
The client can authenticate itself by sending an appropriate HTTPrequest header. The header's name should be X-Api-Key
andits 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 VCU TS Healthchecks API expects request body to bea JSON document (not a multipart/form-data
encodedform data).
API Responses
VCU TS Healthchecks 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 a List of Existing Checks
GET https://healthcheck.ts.vcu.edu/api/v1/checks/
Returns a list of checks belonging to the user, optionally filtered byone 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: https://healthcheck.ts.vcu.edu/api/v1/checks/?tag=foo&tag=bar |
---|
Example Request
curl --header "X-Api-Key: your-api-key" https://healthcheck.ts.vcu.edu/api/v1/checks/
Example Response
{ "checks": [ { "channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc", "desc": "Longer free-form description goes here", "grace": 900, "last_ping": "2017-01-04T13:24:39.903464+00:00", "n_pings": 1, "name": "Api test 1", "next_ping": "2017-01-04T14:24:39.903464+00:00", "pause_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6/pause", "ping_url": "https://healthcheck.ts.vcu.edu/ping/662ebe36-ecab-48db-afe3-e20029cb71e6", "status": "up", "tags": "foo", "timeout": 3600, "update_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/662ebe36-ecab-48db-afe3-e20029cb71e6" }, { "channels": "", "desc": "", "grace": 3600, "last_ping": null, "n_pings": 0, "name": "Api test 2", "next_ping": null, "pause_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause", "ping_url": "https://healthcheck.ts.vcu.edu/ping/9d17c61f-5c4f-4cab-b517-11e6b2679ced", "schedule": "0/10 * * * *", "status": "new", "tags": "bar baz", "tz": "UTC", "update_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced" } ]}
When using the read-only API key, the following fields are omitted: ping_url
, update_url
, pause_url
, channels
. An extra unique_key
field is added. This identifier is stable across API calls. Example:
{ "checks": [ { "desc": "Longer free-form description goes here", "grace": 900, "last_ping": "2017-01-04T13:24:39.903464+00:00", "n_pings": 1, "name": "Api test 1", "status": "up", "tags": "foo", "timeout": 3600, "unique_key": "2872190d95224bad120f41d3c06aab94b8175bb6" }, { "desc": "", "grace": 3600, "last_ping": null, "n_pings": 0, "name": "Api test 2", "next_ping": null, "schedule": "0/10 * * * *", "status": "new", "tags": "bar baz", "tz": "UTC", "unique_key": "9b5fc29129560ff2c5c1803803a7415e4f80cf7e" } ]}
Create a Check
POST https://healthcheck.ts.vcu.edu/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"} |
desc | string, optional. Description for the check. |
timeout | number, optional, default value: 86400. 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: 3600. 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 By default, if a check is created through API, no notification channels (integrations) are assigned to it. So, when the check goes up or down, no notifications will get sent. Set this field to a special value "*" to automatically assign all existing integrations. To assign specific integrations, use a comma-separated list of integration identifiers. Use the Get a List of Existing Integrations call to look up integration identifiers. |
unique | array of string values, optional, default value: []. Before creating a check, look for existing checks, filtered by fields listed in The accepted values are: 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
curl https://healthcheck.ts.vcu.edu/api/v1/checks/ \ --header "X-Api-Key: your-api-key" \ --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
Or, alternatively:
curl https://healthcheck.ts.vcu.edu/api/v1/checks/ \ --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
Example Response
{ "channels": "", "desc": "", "grace": 60, "last_ping": null, "n_pings": 0, "name": "Backups", "next_ping": null, "pause_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", "ping_url": "https://healthcheck.ts.vcu.edu/ping/f618072a-7bde-4eee-af63-71a77c5723bc", "status": "new", "tags": "prod www", "timeout": 3600, "update_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",}
Update an Existing Check
POST https://healthcheck.ts.vcu.edu/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"} |
desc | string, optional. Description for the check. |
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. Set this field to a comma-separated list of channel identifiers to assign specific notification channels. Example: {"channels": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"} |
Response Codes
200 OK | Returned if the check was successfully updated. |
---|
Example Request
curl https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ --header "X-Api-Key: your-api-key" \ --data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
Or, alternatively:
curl https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ --data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
Example Response
{ "channels": "", "desc": "", "grace": 60, "last_ping": null, "n_pings": 0, "name": "Backups", "next_ping": null, "pause_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", "ping_url": "https://healthcheck.ts.vcu.edu/ping/f618072a-7bde-4eee-af63-71a77c5723bc", "status": "new", "tags": "prod www", "timeout": 3600, "update_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",}
Pause Monitoring of a Check
POST https://healthcheck.ts.vcu.edu/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
curl https://healthcheck.ts.vcu.edu/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \ --request POST --header "X-Api-Key: your-api-key" --data ""
Note: the --data ""
argument forces curl to send aContent-Length
request header even though the request bodyis empty. For HTTP POST requests, the Content-Length
headeris sometimes required by some network proxies and web servers.
Example Response
{ "channels": "", "desc": "", "grace": 60, "last_ping": null, "n_pings": 0, "name": "Backups", "next_ping": null, "pause_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", "ping_url": "https://healthcheck.ts.vcu.edu/ping/f618072a-7bde-4eee-af63-71a77c5723bc", "status": "paused", "tags": "prod www", "timeout": 3600, "update_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc"}
Delete Check
DELETE https://healthcheck.ts.vcu.edu/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
curl https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \ --request DELETE --header "X-Api-Key: your-api-key"
Example Response
{ "channels": "", "desc": "", "grace": 60, "last_ping": null, "n_pings": 0, "name": "Backups", "next_ping": null, "pause_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause", "ping_url": "https://healthcheck.ts.vcu.edu/ping/f618072a-7bde-4eee-af63-71a77c5723bc", "status": "new", "tags": "prod www", "timeout": 3600, "update_url": "https://healthcheck.ts.vcu.edu/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",}
Get a List of Existing Integrations
GET https://healthcheck.ts.vcu.edu/api/v1/channels/
Returns a list of integrations belonging to the user.
Example Request
curl --header "X-Api-Key: your-api-key" https://healthcheck.ts.vcu.edu/api/v1/channels/
Example Response
{ "channels": [ { "id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941", "name": "My Work Email", "kind": "email" }, { "id": "746a083e-f542-4554-be1a-707ce16d3acc", "name": "My Phone", "kind": "sms" } ]}