mirror of
https://github.com/healthchecks/healthchecks.git
synced 2024-11-27 01:27:51 +00:00
bdb6f18a3d
The API responses already contain ping_url, update_url, resume_url, pause_url fields where the UUID can be extracted from, so we are not exposing new information. The extraction can be finicky in, say, shell-scripting scenarios. So for API user convenience we will now also provide the check's code (UUID) as a separate field. Fixes: #1007
1333 lines
108 KiB
Plaintext
1333 lines
108 KiB
Plaintext
<h1>Management API v3</h1>
|
|
<p>Version:
|
|
<select onchange="document.location = this.value">
|
|
<option value="../apiv1/">v1</option>
|
|
<option value="../apiv2/">v2</option>
|
|
<option value="../api/" selected>v3</option>
|
|
</select></p>
|
|
<p>With the Management API, you can programmatically manage checks and integrations
|
|
in your account.</p>
|
|
<h2>API Endpoints</h2>
|
|
<div id="api-toc"></div>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Endpoint Name</th>
|
|
<th>Endpoint Address</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><strong>Checks</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#list-checks">List existing checks</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/checks/</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#get-check">Get a single check</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/checks/<uuid></code><br><code>GET SITE_ROOT/api/v3/checks/<unique_key></code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#create-check">Create a new check</a></td>
|
|
<td><code>POST SITE_ROOT/api/v3/checks/</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#update-check">Update an existing check</a></td>
|
|
<td><code>POST SITE_ROOT/api/v3/checks/<uuid></code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#pause-check">Pause monitoring of a check</a></td>
|
|
<td><code>POST SITE_ROOT/api/v3/checks/<uuid>/pause</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#resume-check">Resume monitoring of a check</a></td>
|
|
<td><code>POST SITE_ROOT/api/v3/checks/<uuid>/resume</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#delete-check">Delete check</a></td>
|
|
<td><code>DELETE SITE_ROOT/api/v3/checks/<uuid></code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Pings</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#list-pings">List check's logged pings</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/checks/<uuid>/pings/</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#ping-body">Get a ping's logged body</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/checks/<uuid>/pings/<n>/body</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Flips</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#list-flips">List check's status changes</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/checks/<uuid>/flips/</code><br><code>GET SITE_ROOT/api/v3/checks/<unique_key>/flips/</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Integrations</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#list-channels">List existing integrations</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/channels/</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Badges</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#list-badges">List project's badges</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/badges/</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Service status</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#status">Check database connectivity</a></td>
|
|
<td><code>GET SITE_ROOT/api/v3/status/</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h2>Changes From v2</h2>
|
|
<p>Management API v3 adds the ability to specify custom check slugs, instead of
|
|
auto-generating them from check names. The <a href="#create-check">Create a new check</a>
|
|
and <a href="#update-check">Update an existing check</a> calls accept a new <code>slug</code>
|
|
parameter, and use it instead of generating the slug from the check's name.</p>
|
|
<h2>Authentication</h2>
|
|
<p>Your requests to SITE_NAME Management API must authenticate using an
|
|
API key. All API keys are project-specific. There are no account-wide API keys.
|
|
By default, a project on SITE_NAME doesn't have an API key. You can create read-write
|
|
and read-only API keys on the <strong>Project Settings</strong> page.</p>
|
|
<dl>
|
|
<dt>read-write key</dt>
|
|
<dd>Has full access to all documented API endpoints.</dd>
|
|
<dt>read-only key</dt>
|
|
<dd>
|
|
<p>Only works with the following API endpoints:</p>
|
|
<ul>
|
|
<li><a href="#list-checks">List existing checks</a></li>
|
|
<li><a href="#get-check">Get a single check</a></li>
|
|
<li><a href="#list-flips">List check's status changes</a></li>
|
|
<li><a href="#list-badges">List project's badges</a></li>
|
|
</ul>
|
|
<p>Omits sensitive information from the API responses. See the documentation of
|
|
individual API endpoints for details.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>The client can authenticate itself by including an <code>X-Api-Key: <your-api-key></code>
|
|
header in an HTTP request. Alternatively, for POST requests with a JSON request body,
|
|
the client can put an <code>api_key</code> field in the JSON document.
|
|
See the <a href="#create-check">Create a new check</a> section for an example.</p>
|
|
<h2>API Requests</h2>
|
|
<p>For POST requests, the SITE_NAME API expects the request body to be
|
|
a JSON document (<em>not</em> a <code>multipart/form-data</code> encoded form data).</p>
|
|
<h2>API Responses</h2>
|
|
<p>SITE_NAME uses HTTP status codes wherever possible.
|
|
In general, 2xx class indicates success, 4xx indicates a client error,
|
|
and 5xx indicates a server error.</p>
|
|
<p>The response may contain a JSON document with additional data.</p>
|
|
<h2 class="rule" id="list-checks">List Existing Checks</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/checks/</code></p>
|
|
<p>Returns a list of checks belonging to the user, optionally filtered by
|
|
one or more tags.</p>
|
|
<h3>Query Parameters</h3>
|
|
<dl>
|
|
<dt>slug=<value></dt>
|
|
<dd>
|
|
<p>Filters the checks and returns only the checks with the specified slug.
|
|
If there are no matching checks, returns an empty list. If there are
|
|
multiple matching checks, returns all of them.</p>
|
|
<p>Example:</p>
|
|
<p><code>SITE_ROOT/api/v3/checks/?slug=backups</code></p>
|
|
</dd>
|
|
<dt>tag=<value></dt>
|
|
<dd>
|
|
<p>Filters the checks and returns only the checks that are tagged with the
|
|
specified value.</p>
|
|
<p>This parameter can be repeated multiple times.</p>
|
|
<p>Example:</p>
|
|
<p><code>SITE_ROOT/api/v3/checks/?tag=foo&tag=bar</code></p>
|
|
</dd>
|
|
</dl>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span>SITE_ROOT/api/v3/checks/
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"checks"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Filesystem Backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"filesystem-backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"backup fs"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Runs incremental backup every hour"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">600</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"up"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-24T14:02:03+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-24T15:02:03+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"START"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SUCCESS"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ERROR"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"31365bce-8da9-4729-8ff3-aaa71d56b712"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT31365bce-8da9-4729-8ff3-aaa71d56b712"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Database Backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"database-backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"production db"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Runs ~/db-backup.sh"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"down"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:19:32+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"803f680d-e89b-492b-82ef-2be7b774a92d"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"schedule"</span><span class="p">:</span><span class="w"> </span><span class="s2">"15 5 * * *"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tz"</span><span class="p">:</span><span class="w"> </span><span class="s2">"UTC"</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<p>The possible values for the <code>status</code> field are: <code>new</code>, <code>up</code>, <code>grace</code>, <code>down</code>,
|
|
and <code>paused</code>.</p>
|
|
<p>When using the read-only API key, SITE_NAME omits the following fields from responses:
|
|
<code>uuid</code>, <code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>resume_url</code>, <code>channels</code>. It adds an
|
|
extra <code>unique_key</code> field. The <code>unique_key</code> identifier is stable across API calls, and
|
|
you can use it in the <a href="#get-check">Get a single check</a>
|
|
and <a href="#list-flips">List check's status changes</a> API calls.</p>
|
|
<p>Example:</p>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"checks"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Filesystem Backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"filesystem-backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"backup fs"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Runs incremental backup every hour"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">600</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"up"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-24T14:02:03+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-24T15:02:03+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"START"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SUCCESS"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ERROR"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"unique_key"</span><span class="p">:</span><span class="w"> </span><span class="s2">"a6c7b0a8a66bed0df66abfdab3c77736861703ee"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Database Backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"database-backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"production db"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Runs ~/db-backup.sh"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"down"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:19:32+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"unique_key"</span><span class="p">:</span><span class="w"> </span><span class="s2">"124f983e0e3dcaeba921cfcef46efd084576e783"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"schedule"</span><span class="p">:</span><span class="w"> </span><span class="s2">"15 5 * * *"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tz"</span><span class="p">:</span><span class="w"> </span><span class="s2">"UTC"</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="get-check">Get a Single Check</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/checks/<uuid></code><br>
|
|
<code>GET SITE_ROOT/api/v3/checks/<unique_key></code></p>
|
|
<p>Returns a JSON representation of a single check. Accepts either check's UUID or
|
|
the <code>unique_key</code> (a field derived from UUID and returned by API responses when
|
|
using the read-only API key) as an identifier.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span>SITE_ROOT/api/v3/checks/<uuid>
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Database Backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"database-backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"production db"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Runs ~/db-backup.sh"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"down"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:19:32+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"START"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SUCCESS"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ERROR"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"803f680d-e89b-492b-82ef-2be7b774a92d"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"schedule"</span><span class="p">:</span><span class="w"> </span><span class="s2">"15 5 * * *"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tz"</span><span class="p">:</span><span class="w"> </span><span class="s2">"UTC"</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<p>The possible values for the <code>status</code> field are: <code>new</code>, <code>up</code>, <code>grace</code>, <code>down</code>,
|
|
and <code>paused</code>.</p>
|
|
<h3>Example Read-Only Response</h3>
|
|
<p>When using the read-only API key, SITE_NAME omits the following fields from responses:
|
|
<code>uuid</code>, <code>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>resume_url</code>, <code>channels</code>. It adds an
|
|
extra <code>unique_key</code> field. This identifier is stable across API calls.</p>
|
|
<p>Note: although API omits the <code>*_url</code> fields in read-only API responses, the client can
|
|
easily construct these URLs themselves <em>if</em> they know the check's unique UUID.</p>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Database Backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">"database-backup"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"production db"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Runs ~/db-backup.sh"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"down"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:19:32+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SUCCESS"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SUCCESS"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ERROR"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"unique_key"</span><span class="p">:</span><span class="w"> </span><span class="s2">"124f983e0e3dcaeba921cfcef46efd084576e783"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"schedule"</span><span class="p">:</span><span class="w"> </span><span class="s2">"15 5 * * *"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tz"</span><span class="p">:</span><span class="w"> </span><span class="s2">"UTC"</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="create-check">Create a Check</h2>
|
|
<p><code>POST SITE_ROOT/api/v3/checks/</code></p>
|
|
<p>Creates a new check and returns its ping URL.
|
|
All request parameters are optional and will use their default
|
|
values if omitted.</p>
|
|
<p>With this API call, you can create both Simple and Cron checks:</p>
|
|
<ul>
|
|
<li>To create a Simple check, specify the <code>timeout</code> parameter.</li>
|
|
<li>To create a Cron check, specify the <code>schedule</code> and <code>tz</code> parameters.</li>
|
|
</ul>
|
|
<h3>Request Parameters</h3>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd>
|
|
<p>string, optional, default value: ""</p>
|
|
<p>Name for the new check.</p>
|
|
<p>Changed in API v3: the check's slug is no longer automatically generated
|
|
from the check's name. Instead, the client can specify the slug explicitly
|
|
via the <code>slug</code> field.</p>
|
|
</dd>
|
|
<dt>slug</dt>
|
|
<dd>
|
|
<p>string, optional, default value: ""</p>
|
|
<p>Slug for the new check. The slug should only contain the following
|
|
characters: <code>a-z</code>, <code>0-9</code>, hyphens, underscores. Example:</p>
|
|
<p><pre>{"slug": "my-custom-slug"}</pre></p>
|
|
</dd>
|
|
<dt>tags</dt>
|
|
<dd>
|
|
<p>string, optional, default value: ""</p>
|
|
<p>A space-delimited list of tags for the new check.
|
|
Example:</p>
|
|
<p><pre>{"tags": "reports staging"}</pre></p>
|
|
</dd>
|
|
<dt>desc</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>Description of the check.</p>
|
|
</dd>
|
|
<dt>timeout</dt>
|
|
<dd>
|
|
<p>number, optional, default value: {{ default_timeout }}.</p>
|
|
<p>The expected period of this check in seconds.</p>
|
|
<p>Minimum: 60 (one minute), maximum: 31536000 (365 days).</p>
|
|
<p>Example for a 5-minute timeout:</p>
|
|
<p><pre>{"timeout": 300}</pre></p>
|
|
</dd>
|
|
<dt>grace</dt>
|
|
<dd>
|
|
<p>number, optional, default value: {{ default_grace }}.</p>
|
|
<p>The grace period for this check in seconds.</p>
|
|
<p>Minimum: 60 (one minute), maximum: 31536000 (365 days).</p>
|
|
</dd>
|
|
<dt>schedule</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>A cron or systemd OnCalendar expression defining this check's schedule.
|
|
SITE_NAME will detect the expression type (cron or OnCalendar) automatically.</p>
|
|
<p>The <code>schedule</code> parameter takes precedence over the <code>timeout</code> field: if you specify
|
|
both the <code>timeout</code> and the <code>schedule</code> parameters, SITE_NAME will save the
|
|
<code>schedule</code> and ignore the <code>timeout</code>.</p>
|
|
<p>Example using a cron expression ("run every half-hour"):</p>
|
|
<p><pre>{"schedule": "0,30 * * * *"}</pre></p>
|
|
<p>Example using an OnCalendar expression ("run at 12:00 of the last day of every
|
|
month"):</p>
|
|
<p><pre>{"schedule": "*-*~1 12:00"}</pre></p>
|
|
</dd>
|
|
<dt>tz</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "UTC".</p>
|
|
<p>Server's timezone. This setting only has an effect in combination with the
|
|
<code>schedule</code> parameter.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"tz": "Europe/Riga"}</pre></p>
|
|
</dd>
|
|
<dt>manual_resume</dt>
|
|
<dd>
|
|
<p>boolean, optional, default value: false.</p>
|
|
<p>Controls whether a paused check automatically resumes when pinged (the default)
|
|
or not. If set to false, a paused check will leave the paused state when it receives
|
|
a ping. If set to true, a paused check will ignore pings and stay paused until
|
|
you manually resume it from the web dashboard.</p>
|
|
</dd>
|
|
<dt>methods</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the allowed HTTP methods for making ping requests.
|
|
Must be one of the two values: "" (an empty string) or "POST".</p>
|
|
<p>Set this field to "" (an empty string) to allow HEAD, GET,
|
|
and POST requests.</p>
|
|
<p>Set this field to "POST" to allow only POST requests.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"methods": "POST"}</pre></p>
|
|
</dd>
|
|
<dt>channels</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>By default, this API call assigns no integrations to the newly created
|
|
check.</p>
|
|
<p>Set this field to a special value "*" to automatically assign all existing
|
|
integrations. Example:</p>
|
|
<p><pre>{"channels": "*"}</pre></p>
|
|
<p>To assign specific integrations, use a comma-separated list of integration
|
|
UUIDs. You can look up integration UUIDs using the
|
|
<a href="#list-channels">List Existing Integrations</a> API call.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"channels":
|
|
"4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}</pre></p>
|
|
<p>Alternatively, if you have named your integrations in SITE_NAME dashboard,
|
|
you can specify integrations by their names. For this to work, your integrations
|
|
need non-empty unique names, and they must not contain commas.
|
|
The names must match exactly, whitespace is significant.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"channels": "Email to Alice,SMS to Alice"}</pre></p>
|
|
</dd>
|
|
<dt>unique</dt>
|
|
<dd>
|
|
<p>array of string values, optional, default value: [].</p>
|
|
<p>Enables "upsert" functionality. Before creating a check, SITE_NAME looks for
|
|
existing checks, filtered by fields listed in <code>unique</code>.</p>
|
|
<p>If SITE_NAME does not find a matching check, it creates a new check and returns it
|
|
with the HTTP status code 201.</p>
|
|
<p>If SITE_NAME finds a matching check, it updates the existing check and
|
|
returns it with HTTP status code 200.</p>
|
|
<p>The accepted values for the <code>unique</code> field are
|
|
<code>name</code>, <code>slug</code>, <code>tags</code>, <code>timeout</code>, and <code>grace</code>.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"name": "Backups", unique: ["name"]}</pre></p>
|
|
<p>In this example, if a check named "Backups" exists, it will be returned.
|
|
Otherwise, a new check will be created and returned.</p>
|
|
</dd>
|
|
<dt>start_kw</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Start" signals.
|
|
Separate multiple keywords using commas.</p>
|
|
<p>Use this field in combination with the <code>filter_subject</code> and <code>filter_body</code> fields.
|
|
Setting <code>filter_subject</code> to <code>true</code> enables filtering on the email subject line,
|
|
<code>filter_body</code> enables filtering on the entire email body. SITE_NAME supports both
|
|
plain text and HTML email messages.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"filter_subject": true, "start_kw": "STARTED"}</pre></p>
|
|
<p>In this example, SITE_NAME classifies the email as a start signal if the Subject
|
|
line contains the word "STARTED".</p>
|
|
</dd>
|
|
<dt>success_kw</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Success" signals.
|
|
Separate multiple keywords using commas.</p>
|
|
<p>Use this field in combination with the <code>filter_subject</code> and <code>filter_body</code> fields.
|
|
Setting <code>filter_subject</code> to <code>true</code> enables filtering on the email subject line,
|
|
<code>filter_body</code> enables filtering on the entire email body. SITE_NAME supports both
|
|
plain text and HTML email messages.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"filter_subject": true, "success_kw": "SUCCESS,COMPLETED"}</pre></p>
|
|
<p>In this example, the email counts as success if the Subject line contains either
|
|
the word "SUCCESS" or the word "COMPLETED".</p>
|
|
</dd>
|
|
<dt>failure_kw</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Failure" signals.
|
|
Separate multiple keywords using commas.</p>
|
|
<p>Use this field in combination with the <code>filter_subject</code> and <code>filter_body</code> fields.
|
|
Setting <code>filter_subject</code> to <code>true</code> enables filtering on the email subject line,
|
|
<code>filter_body</code> enables filtering on the entire email body. SITE_NAME supports both
|
|
plain text and HTML email messages.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"filter_subject": true, "failure_kw": "FAILED, ERROR"}</pre></p>
|
|
<p>In this example, the email counts as failure if the Subject line contains either
|
|
the word "FAILED" or the word "ERROR".</p>
|
|
</dd>
|
|
<dt>filter_subject</dt>
|
|
<dd>
|
|
<p>boolean, optional, default value: false.</p>
|
|
<p>Enables filtering of inbound email messages by looking for keywords in their
|
|
subject lines. See also the <code>success_kw</code> and <code>failure_kw</code> fields.</p>
|
|
</dd>
|
|
<dt>filter_body</dt>
|
|
<dd>
|
|
<p>boolean, optional, default value: false.</p>
|
|
<p>Enables filtering of inbound email messages by looking for keywords in their
|
|
message body. See also the <code>success_kw</code> and <code>failure_kw</code> fields.</p>
|
|
</dd>
|
|
<dt>subject</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p><strong>Deprecated</strong>. Use the <code>success_kw</code>, <code>filter_subject</code> and <code>filter_body</code> fields
|
|
instead.</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Success" signals.
|
|
Separate multiple keywords using commas. If any of the keywords is found in
|
|
an email message's Subject line, the email message will count as "Success".</p>
|
|
<p>Set this field to "" (an empty string) to consider all inbound email messages as
|
|
"Success" (unless they match any keywords listed in <code>subject_fail</code> and are thus
|
|
classified as "Failure").</p>
|
|
<p>Example:</p>
|
|
<p><pre>SUCCESS,COMPLETED</pre></p>
|
|
<p>In this example, the email counts as success if the Subject line contains either
|
|
the word "SUCCESS" or the word "COMPLETED".</p>
|
|
</dd>
|
|
<dt>subject_fail</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p><strong>Deprecated</strong>. Use the <code>failure_kw</code>, <code>filter_subject</code> and <code>filter_body</code> fields
|
|
instead.</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Failure" signals.
|
|
Separate multiple keywords using commas. If any of the keywords is found in
|
|
an email message's Subject line, the email message will count as "Failure".</p>
|
|
<p>Set this field to "" (an empty string) to perform no "Failure" classification.</p>
|
|
<p>Example:</p>
|
|
<p><pre>FAILED,ERROR</pre></p>
|
|
<p>In this example, the email counts as failure if the Subject line contains either
|
|
the word "FAILED" or the word "ERROR".</p>
|
|
</dd>
|
|
</dl>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>201 Created</dt>
|
|
<dd>A new check was successfully created.</dd>
|
|
<dt>200 OK</dt>
|
|
<dd>An existing check was found and updated.</dd>
|
|
<dt>400 Bad Request</dt>
|
|
<dd>The request is not well-formed, violates schema, or uses invalid
|
|
field values.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>The account has hit its check limit. For free accounts,
|
|
the limit is 20 checks per account.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--data<span class="w"> </span><span class="s1">'{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'</span>
|
|
</code></pre></div>
|
|
|
|
<p>Or, alternatively:</p>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--data<span class="w"> </span><span class="s1">'{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'</span>
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Backups"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prod www"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">60</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"new"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject_fail"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="update-check">Update an Existing Check</h2>
|
|
<p><code>POST SITE_ROOT/api/v3/checks/<uuid></code></p>
|
|
<p>Updates an existing check. All request parameters are optional. If you omit any
|
|
parameter, SITE_NAME will leave its value unchanged.</p>
|
|
<h3>Request Parameters</h3>
|
|
<dl>
|
|
<dt>name</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>Name for the check.</p>
|
|
<p>Changed in API v3: the check's slug is no longer automatically generated
|
|
from the check's name. Instead, the client can specify the slug explicitly
|
|
via the <code>slug</code> field.</p>
|
|
</dd>
|
|
<dt>slug</dt>
|
|
<dd>
|
|
<p>string, optional</p>
|
|
<p>Slug for the new check. The slug should only contain the following
|
|
characters: <code>a-z</code>, <code>0-9</code>, hyphens, underscores. Example:</p>
|
|
<p><pre>{"slug": "my-custom-slug"}</pre></p>
|
|
</dd>
|
|
<dt>tags</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>A space-delimited list of tags for the check.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"tags": "reports staging"}</pre></p>
|
|
</dd>
|
|
<dt>desc</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>Description of the check.</p>
|
|
</dd>
|
|
<dt>timeout</dt>
|
|
<dd>
|
|
<p>number, optional.</p>
|
|
<p>The expected period of this check in seconds.</p>
|
|
<p>Minimum: 60 (one minute), maximum: 31536000 (365 days).</p>
|
|
<p>Example for a 5-minute timeout:</p>
|
|
<p><pre>{"timeout": 300}</pre></p>
|
|
</dd>
|
|
<dt>grace</dt>
|
|
<dd>
|
|
<p>number, optional.</p>
|
|
<p>The grace period for this check in seconds.</p>
|
|
<p>Minimum: 60 (one minute), maximum: 31536000 (365 days).</p>
|
|
</dd>
|
|
<dt>schedule</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>A cron or systemd OnCalendar expression defining this check's schedule.
|
|
SITE_NAME will detect the expression type (cron or OnCalendar) automatically.</p>
|
|
<p>The <code>schedule</code> parameter takes precedence over the <code>timeout</code> field: If you specify
|
|
both the <code>timeout</code> and the <code>schedule</code> parameters, SITE_NAME will save the
|
|
<code>schedule</code> and ignore the <code>timeout</code>.</p>
|
|
<p>Example using a cron expression ("run every half-hour"):</p>
|
|
<p><pre>{"schedule": "0,30 * * * *"}</pre></p>
|
|
<p>Example using an OnCalendar expression ("run at 12:00 of the last day of every
|
|
month"):</p>
|
|
<p><pre>{"schedule": "*-*~1 12:00"}</pre></p>
|
|
</dd>
|
|
<dt>tz</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>Server's timezone. This setting only has an effect in combination with the
|
|
"schedule" parameter.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"tz": "Europe/Riga"}</pre></p>
|
|
</dd>
|
|
<dt>manual_resume</dt>
|
|
<dd>
|
|
<p>boolean, optional, default value: false.</p>
|
|
<p>Controls whether a paused ping automatically resumes when pinged (the default),
|
|
or not. If set to false, a paused check will leave the paused state when it receives
|
|
a ping. If set to true, a paused check will ignore pings and stay paused until
|
|
you manually resume it from the web dashboard.</p>
|
|
</dd>
|
|
<dt>methods</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the allowed HTTP methods for making ping requests.
|
|
Must be one of the two values: "" (an empty string) or "POST".</p>
|
|
<p>Set this field to "" (an empty string) to allow HEAD, GET,
|
|
and POST requests.</p>
|
|
<p>Set this field to "POST" to allow only POST requests.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"methods": "POST"}</pre></p>
|
|
</dd>
|
|
<dt>channels</dt>
|
|
<dd>
|
|
<p>string, optional.</p>
|
|
<p>Set this field to a special value "*" to automatically assign all existing
|
|
integrations. Example:</p>
|
|
<p><pre>{"channels": "*"}</pre></p>
|
|
<p>Set this field to a special value "" (empty string) to automatically <em>unassign</em>
|
|
all existing integrations. Example:</p>
|
|
<p><pre>{"channels": ""}</pre></p>
|
|
<p>To assign specific integrations, use a comma-separated list of integration
|
|
UUIDs. You can look up integration UUIDs using the
|
|
<a href="#list-channels">List Existing Integrations</a> API call.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"channels":
|
|
"4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}</pre></p>
|
|
<p>Alternatively, if you have named your integrations in SITE_NAME dashboard,
|
|
you can specify integrations by their names. For this to work, your integrations
|
|
need non-empty and unique names, and they must not contain commas. The names
|
|
must match exactly, whitespace is significant.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"channels": "Email to Alice,SMS to Alice"}</pre></p>
|
|
</dd>
|
|
<dt>start_kw</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Start" signals.
|
|
Separate multiple keywords using commas.</p>
|
|
<p>Use this field in combination with the <code>filter_subject</code> and <code>filter_body</code> fields.
|
|
Setting <code>filter_subject</code> to <code>true</code> enables filtering on the email subject line,
|
|
<code>filter_body</code> enables filtering on the entire email body. SITE_NAME supports both
|
|
plain text and HTML email messages.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"filter_subject": true, "start_kw": "STARTED"}</pre></p>
|
|
<p>In this example, SITE_NAME classifies the email as a start signal if the Subject
|
|
line contains the word "STARTED".</p>
|
|
</dd>
|
|
<dt>success_kw</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Success" signals.
|
|
Separate multiple keywords using commas.</p>
|
|
<p>Use this field in combination with the <code>filter_subject</code> and <code>filter_body</code> fields.
|
|
Setting <code>filter_subject</code> to <code>true</code> enables filtering on the email subject line,
|
|
<code>filter_body</code> enables filtering on the entire email body. SITE_NAME supports both
|
|
plain text and HTML email messages.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"filter_subject": true, "success_kw": "SUCCESS,COMPLETED"}</pre></p>
|
|
<p>In this example, the email counts as success if the Subject line contains either
|
|
the word "SUCCESS" or the word "COMPLETED".</p>
|
|
</dd>
|
|
<dt>failure_kw</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Failure" signals.
|
|
Separate multiple keywords using commas.</p>
|
|
<p>Use this field in combination with the <code>filter_subject</code> and <code>filter_body</code> fields.
|
|
Setting <code>filter_subject</code> to <code>true</code> enables filtering on the email subject line,
|
|
<code>filter_body</code> enables filtering on the entire email body. SITE_NAME supports both
|
|
plain text and HTML email messages.</p>
|
|
<p>Example:</p>
|
|
<p><pre>{"filter_subject": true, "failure_kw": "FAILED, ERROR"}</pre></p>
|
|
<p>In this example, the email counts as failure if the Subject line contains either
|
|
the word "FAILED" or the word "ERROR".</p>
|
|
</dd>
|
|
<dt>filter_subject</dt>
|
|
<dd>
|
|
<p>boolean, optional, default value: false.</p>
|
|
<p>Enables filtering of inbound email messages by looking for keywords in their
|
|
subject lines. See also the <code>success_kw</code> and <code>failure_kw</code> fields.</p>
|
|
</dd>
|
|
<dt>filter_body</dt>
|
|
<dd>
|
|
<p>boolean, optional, default value: false.</p>
|
|
<p>Enables filtering of inbound email messages by looking for keywords in their
|
|
message body. See also the <code>success_kw</code> and <code>failure_kw</code> fields.</p>
|
|
</dd>
|
|
<dt>subject</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p><strong>Deprecated</strong>. Use the <code>success_kw</code>, <code>filter_subject</code> and <code>filter_body</code> fields
|
|
instead.</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Success" signals.
|
|
Separate multiple keywords using commas. If any of the keywords is found in
|
|
an email message's Subject line, the email message will count as "Success".</p>
|
|
<p>Set this field to "" (an empty string) to consider all inbound email messages as
|
|
"Success" (unless they match any keywords listed in <code>subject_fail</code> and are thus
|
|
classified as "Failure").</p>
|
|
<p>Example:</p>
|
|
<p><pre>SUCCESS,COMPLETED</pre></p>
|
|
<p>In this example, the email counts as success if the Subject line contains either
|
|
the word "SUCCESS" or the word "COMPLETED".</p>
|
|
</dd>
|
|
<dt>subject_fail</dt>
|
|
<dd>
|
|
<p>string, optional, default value: "".</p>
|
|
<p><strong>Deprecated</strong>. Use the <code>failure_kw</code>, <code>filter_subject</code> and <code>filter_body</code> fields
|
|
instead.</p>
|
|
<p>Specifies the keywords for classifying inbound email messages as "Failure" signals.
|
|
Separate multiple keywords using commas. If any of the keywords is found in
|
|
an email message's Subject line, the email message will count as "Failure".</p>
|
|
<p>Set this field to "" (an empty string) to perform no "Failure" classification.</p>
|
|
<p>Example:</p>
|
|
<p><pre>FAILED,ERROR</pre></p>
|
|
<p>In this example, the email counts as failure if the Subject line contains either
|
|
the word "FAILED" or the word "ERROR".</p>
|
|
</dd>
|
|
</dl>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The check was successfully updated.</dd>
|
|
<dt>400 Bad Request</dt>
|
|
<dd>The request is not well-formed, violates schema, or uses invalid
|
|
field values.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--data<span class="w"> </span><span class="s1">'{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'</span>
|
|
</code></pre></div>
|
|
|
|
<p>Or, alternatively:</p>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--data<span class="w"> </span><span class="s1">'{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'</span>
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Backups"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prod www"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">60</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"new"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject_fail"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="pause-check">Pause Monitoring of a Check</h2>
|
|
<p><code>POST SITE_ROOT/api/v3/checks/<uuid>/pause</code></p>
|
|
<p>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, or by running
|
|
the <a href="#resume-check">Resume</a> API call (useful when check's <code>manual_resume=True</code>).</p>
|
|
<p>This API call has no request parameters.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The check was successfully paused.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--request<span class="w"> </span>POST<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span>--data<span class="w"> </span><span class="s2">""</span>
|
|
</code></pre></div>
|
|
|
|
<p>Note: the <code>--data ""</code> argument forces curl to send a <code>Content-Length</code> request header
|
|
even though the request body is empty. For HTTP POST requests, the <code>Content-Length</code>
|
|
header is sometimes required by some network proxies and web servers.</p>
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Backups"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prod www"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">60</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"paused"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject_fail"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="resume-check">Resume Monitoring of a Check</h2>
|
|
<p><code>POST SITE_ROOT/api/v3/checks/<uuid>/resume</code></p>
|
|
<p>Resumes a check. The check goes into the "new" state. Use this API call to resume
|
|
the monitoring of checks that are in the paused state, and have the <code>manual_resume</code>
|
|
configuration parameter set to <code>True</code>.</p>
|
|
<p>This API call has no request parameters.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The operation was successful.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
<dt>409 Conflict</dt>
|
|
<dd>The specified check is currently not in a paused state.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--request<span class="w"> </span>POST<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span>--data<span class="w"> </span><span class="s2">""</span>
|
|
</code></pre></div>
|
|
|
|
<p>Note: the <code>--data ""</code> argument forces curl to send a <code>Content-Length</code> request header
|
|
even though the request body is empty. For HTTP POST requests, the <code>Content-Length</code>
|
|
header is sometimes required by some network proxies and web servers.</p>
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Backups"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prod www"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">60</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"new"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject_fail"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="delete-check">Delete Check</h2>
|
|
<p><code>DELETE SITE_ROOT/api/v3/checks/<uuid></code></p>
|
|
<p>Permanently deletes the check from the user's account. Returns JSON representation of the
|
|
check that was just deleted.</p>
|
|
<p>This API call has no request parameters.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The check was successfully deleted.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--request<span class="w"> </span>DELETE<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span>
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Backups"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"slug"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"tags"</span><span class="p">:</span><span class="w"> </span><span class="s2">"prod www"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"desc"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"grace"</span><span class="p">:</span><span class="w"> </span><span class="mi">60</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n_pings"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"new"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"started"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"last_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"next_ping"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"manual_resume"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"methods"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"subject_fail"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"success_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"failure_kw"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_subject"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"filter_body"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ping_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"PING_ENDPOINT7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"update_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pause_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"resume_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"timeout"</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="list-pings">List check's logged pings</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/checks/<uuid>/pings/</code></p>
|
|
<p>Returns a list of pings this check has received.</p>
|
|
<p>This endpoint returns pings in reverse order (most recent first), and the total
|
|
number of returned pings depends on the account's billing plan: 100 for free accounts,
|
|
1000 for paid accounts.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span>
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"pings"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"success"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"date"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-06-09T14:51:06.113073+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n"</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scheme"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"remote_addr"</span><span class="p">:</span><span class="w"> </span><span class="s2">"192.0.2.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"method"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GET"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ua"</span><span class="p">:</span><span class="w"> </span><span class="s2">"curl/7.68.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"rid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"123e4567-e89b-12d3-a456-426614174000"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"duration"</span><span class="p">:</span><span class="w"> </span><span class="mf">2.896736</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"body_url"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"start"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"date"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-06-09T14:51:03.216337+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scheme"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"remote_addr"</span><span class="p">:</span><span class="w"> </span><span class="s2">"192.0.2.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"method"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GET"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ua"</span><span class="p">:</span><span class="w"> </span><span class="s2">"curl/7.68.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"rid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"123e4567-e89b-12d3-a456-426614174000"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"body_url"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"success"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"date"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-06-09T14:50:59.633577+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n"</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scheme"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"remote_addr"</span><span class="p">:</span><span class="w"> </span><span class="s2">"192.0.2.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"method"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GET"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ua"</span><span class="p">:</span><span class="w"> </span><span class="s2">"curl/7.68.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"rid"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"duration"</span><span class="p">:</span><span class="w"> </span><span class="mf">2.997976</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"body_url"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"start"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"date"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-06-09T14:50:56.635601+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"n"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scheme"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"remote_addr"</span><span class="p">:</span><span class="w"> </span><span class="s2">"192.0.2.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"method"</span><span class="p">:</span><span class="w"> </span><span class="s2">"GET"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ua"</span><span class="p">:</span><span class="w"> </span><span class="s2">"curl/7.68.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"rid"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"body_url"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="ping-body">Get a ping's logged body</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/checks/<uuid>/pings/<n>/body</code></p>
|
|
<p>Returns a ping's logged body. The response always has the <code>Content-Type: text/plain</code>
|
|
response header and the ping body is returned verbatim in the response body.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded and a body is present.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The check does not exist, the ping does not exist, or the ping has no body data.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="list-flips">List check's status changes</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/checks/<uuid>/flips/</code><br>
|
|
<code>GET SITE_ROOT/api/v3/checks/<unique_key>/flips/</code></p>
|
|
<p>Returns a list of "flips" this check has experienced. A flip is a change of status
|
|
(from "down" to "up," or from "up" to "down").</p>
|
|
<p>This API endpoint supports time filtering via the <code>seconds</code>, <code>start</code>, and <code>end</code> query
|
|
parameters. If no time filters are specified, the API returns all stored
|
|
flips for a given check.</p>
|
|
<p>Notes about flip retention: SITE_NAME stores historic flips for the current month
|
|
and for two full months prior to the current month. The cleanup of older flips is
|
|
<a href="../self_hosted/#database-cleanup">a manual administrative action</a>.
|
|
Therefore, SITE_NAME may return even older flips if the server administrator does not
|
|
perform regular database cleanups.</p>
|
|
<h3>Query Parameters</h3>
|
|
<dl>
|
|
<dt>seconds=<value></dt>
|
|
<dd>
|
|
<p>Returns the flips from the last <code>value</code> seconds</p>
|
|
<p>Example:</p>
|
|
<p><code>SITE_ROOT/api/v3/checks/<uuid|unique_key>/flips/?seconds=3600</code></p>
|
|
</dd>
|
|
<dt>start=<value></dt>
|
|
<dd>
|
|
<p>Returns flips that are newer than the specified UNIX timestamp.</p>
|
|
<p>Example:</p>
|
|
<p><code>SITE_ROOT/api/v3/checks/<uuid|unique_key>/flips/?start=1592214380</code></p>
|
|
</dd>
|
|
<dt>end=<value></dt>
|
|
<dd>
|
|
<p>Returns flips that are older than the specified UNIX timestamp.</p>
|
|
<p>Example:</p>
|
|
<p><code>SITE_ROOT/api/v3/checks/<uuid|unique_key>/flips/?end=1592217980</code></p>
|
|
</dd>
|
|
</dl>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>400 Bad Request</dt>
|
|
<dd>Invalid query parameters.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
<dt>403 Forbidden</dt>
|
|
<dd>Access denied, wrong API key.</dd>
|
|
<dt>404 Not Found</dt>
|
|
<dd>The specified check does not exist.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>SITE_ROOT/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/<span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span>
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:18:23+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"up"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:17:15+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"up"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2020-03-23T10:16:18+00:00"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"up"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="p">]</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="list-channels">List Existing Integrations</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/channels/</code></p>
|
|
<p>Returns a list of integrations belonging to the project.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span>SITE_ROOT/api/v3/channels/
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"channels"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"4ec5a071-2d08-4baa-898a-eb4eb3cd6941"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"My Work Email"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"kind"</span><span class="p">:</span><span class="w"> </span><span class="s2">"email"</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"746a083e-f542-4554-be1a-707ce16d3acc"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"My Phone"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"kind"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sms"</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="list-badges">List Project's Badges</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/badges/</code></p>
|
|
<p>Returns a map of all tags in the project, with badge URLs for each tag. SITE_NAME
|
|
provides badges in a few different formats:</p>
|
|
<ul>
|
|
<li><code>svg</code>: returns the badge as an SVG document.</li>
|
|
<li><code>json</code>: returns a JSON document which you can use to generate a custom badge
|
|
yourself.</li>
|
|
<li><code>shields</code>: returns JSON in a <a href="https://shields.io/endpoint">Shields.io compatible format</a>.</li>
|
|
</ul>
|
|
<p>In addition, badges have 2-state and 3-state variations:</p>
|
|
<ul>
|
|
<li><code>svg</code>, <code>json</code>, <code>shields</code>: reports two states: "up" and "down". It
|
|
considers any checks in the grace period as still "up".</li>
|
|
<li><code>svg3</code>, <code>json3</code>, <code>shields3</code>: reports three states: "up", "late", and "down".</li>
|
|
</ul>
|
|
<p>The response includes a special <code>*</code> entry: this pseudo-tag reports the overall status
|
|
of all checks in the project.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>401 Unauthorized</dt>
|
|
<dd>The API key is either missing or invalid.</dd>
|
|
</dl>
|
|
<h3>Example Request</h3>
|
|
<div class="highlight"><pre><span></span><code>curl<span class="w"> </span>--header<span class="w"> </span><span class="s2">"X-Api-Key: your-api-key"</span><span class="w"> </span>SITE_ROOT/api/v3/badges/
|
|
</code></pre></div>
|
|
|
|
<h3>Example Response</h3>
|
|
<div class="highlight"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"badges"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"backup"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"svg"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"svg3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.shields"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.shields"</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"db"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"svg"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"svg3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.shields"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.shields"</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"prod"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"svg"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"svg3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.shields"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.shields"</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"*"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"svg"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"svg3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.svg"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"json3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.json"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.shields"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"shields3"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.shields"</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h2 class="rule" id="status">Check Database Connectivity</h2>
|
|
<p><code>GET SITE_ROOT/api/v3/status/</code></p>
|
|
<p>Runs a test query and returns HTTP 200 if the query completes successfully.
|
|
Use this endpoint to monitor the uptime of your Healthchecks instance with an
|
|
external uptime monitoring system.</p>
|
|
<h3>Response Codes</h3>
|
|
<dl>
|
|
<dt>200 OK</dt>
|
|
<dd>The request succeeded.</dd>
|
|
<dt>500 Internal Server Error</dt>
|
|
<dd>Test database query did not succeed.</dd>
|
|
</dl> |