nielsperetzke
/
healthchecks
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 32 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1874 Commits
2 Branches
15 MiB
 
 
 
 
 
Tree: 1b513c0802
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '1b513c0802'
${ noResults }
healthchecks/templates/docs/api.html

893 lines
59 KiB
Raw Blame History

<h1>Management API</h1>
<p>With the Management API, you can programmatically manage checks and integrations
in your account.</p>
<h2>API Endpoints</h2>
<table>
<thead>
<tr>
<th>Endpoint Name</th>
<th>Endpoint Address</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#list-checks">Get a list of existing checks</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/</code></td>
</tr>
<tr>
<td><a href="#get-check">Get a single check</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code><br><code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;</code></td>
</tr>
<tr>
<td><a href="#create-check">Create a new check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/</code></td>
</tr>
<tr>
<td><a href="#update-check">Update an existing check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></td>
</tr>
<tr>
<td><a href="#pause-check">Pause monitoring of a check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pause</code></td>
</tr>
<tr>
<td><a href="#delete-check">Delete check</a></td>
<td><code>DELETE SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></td>
</tr>
<tr>
<td><a href="#list-pings">Get a list of check's logged pings</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/</code></td>
</tr>
<tr>
<td><a href="#list-flips">Get a list of check's status changes</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/flips/</code><br><code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;/flips/</code></td>
</tr>
<tr>
<td><a href="#list-channels">Get a list of existing integrations</a></td>
<td><code>GET SITE_ROOT/api/v1/channels/</code></td>
</tr>
<tr>
<td><a href="#list-badges">Get project's badges</a></td>
<td><code>GET SITE_ROOT/api/v1/badges/</code></td>
</tr>
</tbody>
</table>
<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">Get a list of existing checks</a></li>
<li><a href="#get-check">Get a single check</a></li>
<li><a href="#list-flips">Get a list of check's status changes</a></li>
<li><a href="#list-badges">Get 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: &lt;your-api-key&gt;</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">Get a List of Existing Checks</h2>
<p><code>GET SITE_ROOT/api/v1/checks/</code></p>
<p>Returns a list of checks belonging to the user, optionally filtered by
one or more tags.</p>
<h3>Query String Parameters</h3>
<dl>
<dt>tag=&lt;value&gt;</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/v1/checks/?tag=foo&amp;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 --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/checks/
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;checks&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Filesystem Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;filesystem-backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;backup fs&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Runs incremental backup every hour&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">600</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;up&quot;</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T14:02:03+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T15:02:03+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINT31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c&quot;</span><span class="p">,</span>
<span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Database Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;database-backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;production db&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Runs ~/db-backup.sh&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">1200</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c&quot;</span><span class="p">,</span>
<span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span>
<span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span>
<span class="p">}</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>started</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>ping_url</code>, <code>update_url</code>, <code>pause_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">Get a list of check's status changes</a> API calls.</p>
<p>Example:</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;checks&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Filesystem Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;filesystem-backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;backup fs&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Runs incremental backup every hour&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">600</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;up&quot;</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T14:02:03+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-24T15:02:03+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;a6c7b0a8a66bed0df66abfdab3c77736861703ee&quot;</span><span class="p">,</span>
<span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Database Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;database-backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;production db&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Runs ~/db-backup.sh&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">1200</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;124f983e0e3dcaeba921cfcef46efd084576e783&quot;</span><span class="p">,</span>
<span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span>
<span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span>
<span class="p">}</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/v1/checks/&lt;uuid&gt;</code><br>
<code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;</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 --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/checks/&lt;uuid&gt;
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Database Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;database-backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;production db&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Runs ~/db-backup.sh&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">1200</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c&quot;</span><span class="p">,</span>
<span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span>
<span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span>
<span class="p">}</span>
</code></pre></div>
<p>The possible values for the <code>status</code> field are: <code>new</code>, <code>started</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>ping_url</code>, <code>update_url</code>, <code>pause_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>ping_url</code>, <code>update_url</code>, and <code>pause_url</code> 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="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Database Backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;database-backup&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;production db&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;Runs ~/db-backup.sh&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">1200</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;down&quot;</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;unique_key&quot;</span><span class="p">:</span> <span class="s2">&quot;124f983e0e3dcaeba921cfcef46efd084576e783&quot;</span><span class="p">,</span>
<span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span>
<span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span>
<span class="p">}</span>
</code></pre></div>
<h2 class="rule" id="create-check">Create a Check</h2>
<p><code>POST SITE_ROOT/api/v1/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>
</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, default value: "<code>* * * * *</code>".</p>
<p>A cron expression defining this check's schedule.</p>
<p>If you specify both <code>timeout</code> and <code>schedule</code> parameters,
SITE_NAME will create a Cron check and ignore
the <code>timeout</code> value.</p>
<p>Example for a check running every half-hour:</p>
<p><pre>{"schedule": "0,30 * <em> * </em>"}</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">Get a List of 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>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>
</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 SITE_ROOT/api/v1/checks/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> <span class="se">\</span>
--data <span class="s1">&#39;{&quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
<p>Or, alternatively:</p>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/ <span class="se">\</span>
--data <span class="s1">&#39;{&quot;api_key&quot;: &quot;your-api-key&quot;, &quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">60</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;prod www&quot;</span><span class="p">,</span>
<span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</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/v1/checks/&lt;uuid&gt;</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>
</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 expression defining this check's schedule.</p>
<p>If you specify both <code>timeout</code> and <code>schedule</code> parameters,
SITE_NAME will save the <code>schedule</code> parameter and ignore
the <code>timeout</code>.</p>
<p>Example for a check running every half-hour:</p>
<p><pre>{"schedule": "0,30 * <em> * </em>"}</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">Get a List of 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>
</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 SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> <span class="se">\</span>
--data <span class="s1">&#39;{&quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
<p>Or, alternatively:</p>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
--data <span class="s1">&#39;{&quot;api_key&quot;: &quot;your-api-key&quot;, &quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">60</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;prod www&quot;</span><span class="p">,</span>
<span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</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/v1/checks/&lt;uuid&gt;/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.</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 SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause <span class="se">\</span>
--request POST --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> --data <span class="s2">&quot;&quot;</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="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">60</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;paused&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;prod www&quot;</span><span class="p">,</span>
<span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span>
<span class="p">}</span>
</code></pre></div>
<h2 class="rule" id="delete-check">Delete Check</h2>
<p><code>DELETE SITE_ROOT/api/v1/checks/&lt;uuid&gt;</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 SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
--request DELETE --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;desc&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">60</span><span class="p">,</span>
<span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;slug&quot;</span><span class="p">:</span> <span class="s2">&quot;backups&quot;</span><span class="p">,</span>
<span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&quot;methods&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span>
<span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
<span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
<span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;prod www&quot;</span><span class="p">,</span>
<span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
<span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div>
<h2 class="rule" id="list-pings">Get a list of check's logged pings</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/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 SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;pings&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span><span class="p">,</span>
<span class="nt">&quot;date&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-06-09T14:51:06.113073+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;n&quot;</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span>
<span class="nt">&quot;scheme&quot;</span><span class="p">:</span> <span class="s2">&quot;http&quot;</span><span class="p">,</span>
<span class="nt">&quot;remote_addr&quot;</span><span class="p">:</span> <span class="s2">&quot;192.0.2.0&quot;</span><span class="p">,</span>
<span class="nt">&quot;method&quot;</span><span class="p">:</span> <span class="s2">&quot;GET&quot;</span><span class="p">,</span>
<span class="nt">&quot;ua&quot;</span><span class="p">:</span> <span class="s2">&quot;curl/7.68.0&quot;</span><span class="p">,</span>
<span class="nt">&quot;duration&quot;</span><span class="p">:</span> <span class="mf">2.896736</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;start&quot;</span><span class="p">,</span>
<span class="nt">&quot;date&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-06-09T14:51:03.216337+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;n&quot;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span>
<span class="nt">&quot;scheme&quot;</span><span class="p">:</span> <span class="s2">&quot;http&quot;</span><span class="p">,</span>
<span class="nt">&quot;remote_addr&quot;</span><span class="p">:</span> <span class="s2">&quot;192.0.2.0&quot;</span><span class="p">,</span>
<span class="nt">&quot;method&quot;</span><span class="p">:</span> <span class="s2">&quot;GET&quot;</span><span class="p">,</span>
<span class="nt">&quot;ua&quot;</span><span class="p">:</span> <span class="s2">&quot;curl/7.68.0&quot;</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;success&quot;</span><span class="p">,</span>
<span class="nt">&quot;date&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-06-09T14:50:59.633577+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;n&quot;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
<span class="nt">&quot;scheme&quot;</span><span class="p">:</span> <span class="s2">&quot;http&quot;</span><span class="p">,</span>
<span class="nt">&quot;remote_addr&quot;</span><span class="p">:</span> <span class="s2">&quot;192.0.2.0&quot;</span><span class="p">,</span>
<span class="nt">&quot;method&quot;</span><span class="p">:</span> <span class="s2">&quot;GET&quot;</span><span class="p">,</span>
<span class="nt">&quot;ua&quot;</span><span class="p">:</span> <span class="s2">&quot;curl/7.68.0&quot;</span><span class="p">,</span>
<span class="nt">&quot;duration&quot;</span><span class="p">:</span> <span class="mf">2.997976</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;start&quot;</span><span class="p">,</span>
<span class="nt">&quot;date&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-06-09T14:50:56.635601+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;n&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="nt">&quot;scheme&quot;</span><span class="p">:</span> <span class="s2">&quot;http&quot;</span><span class="p">,</span>
<span class="nt">&quot;remote_addr&quot;</span><span class="p">:</span> <span class="s2">&quot;192.0.2.0&quot;</span><span class="p">,</span>
<span class="nt">&quot;method&quot;</span><span class="p">:</span> <span class="s2">&quot;GET&quot;</span><span class="p">,</span>
<span class="nt">&quot;ua&quot;</span><span class="p">:</span> <span class="s2">&quot;curl/7.68.0&quot;</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
</code></pre></div>
<h2 class="rule" id="list-flips">Get a list of check's status changes</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/flips/</code><br>
<code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;/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>
<h3>Query String Parameters</h3>
<dl>
<dt>seconds=&lt;value&gt;</dt>
<dd>
<p>Returns the flips from the last <code>value</code> seconds</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?seconds=3600</code></p>
</dd>
<dt>start=&lt;value&gt;</dt>
<dd>
<p>Returns flips that are newer than the specified UNIX timestamp.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?start=1592214380</code></p>
</dd>
<dt>end=&lt;value&gt;</dt>
<dd>
<p>Returns flips that are older than the specified UNIX timestamp.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/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 SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:18:23+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;up&quot;</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:17:15+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;up&quot;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2020-03-23T10:16:18+00:00&quot;</span><span class="p">,</span>
<span class="nt">&quot;up&quot;</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">}</span>
<span class="p">]</span>
</code></pre></div>
<h2 class="rule" id="list-channels">Get a List of Existing Integrations</h2>
<p><code>GET SITE_ROOT/api/v1/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 --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/channels/
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;channels&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;id&quot;</span><span class="p">:</span> <span class="s2">&quot;4ec5a071-2d08-4baa-898a-eb4eb3cd6941&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;My Work Email&quot;</span><span class="p">,</span>
<span class="nt">&quot;kind&quot;</span><span class="p">:</span> <span class="s2">&quot;email&quot;</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;id&quot;</span><span class="p">:</span> <span class="s2">&quot;746a083e-f542-4554-be1a-707ce16d3acc&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;My Phone&quot;</span><span class="p">,</span>
<span class="nt">&quot;kind&quot;</span><span class="p">:</span> <span class="s2">&quot;sms&quot;</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
</code></pre></div>
<h2 class="rule" id="list-badges">Get Project's Badges</h2>
<p><code>GET SITE_ROOT/api/v1/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 a 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 overal 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 --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/badges/
</code></pre></div>
<h3>Example Response</h3>
<div class="highlight"><pre><span></span><code><span class="p">{</span>
<span class="nt">&quot;badges&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;backup&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;svg&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;svg3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;json&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;json3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.shields&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.shields&quot;</span>
<span class="p">},</span>
<span class="nt">&quot;db&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;svg&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;svg3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;json&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;json3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.shields&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.shields&quot;</span>
<span class="p">},</span>
<span class="nt">&quot;prod&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;svg&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;svg3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;json&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;json3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.shields&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.shields&quot;</span>
<span class="p">},</span>
<span class="nt">&quot;*&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;svg&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;svg3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.svg&quot;</span><span class="p">,</span>
<span class="nt">&quot;json&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;json3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.json&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.shields&quot;</span><span class="p">,</span>
<span class="nt">&quot;shields3&quot;</span><span class="p">:</span> <span class="s2">&quot;SITE_ROOT/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.shields&quot;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div>