mirror of
https://github.com/healthchecks/healthchecks.git
synced 2025-02-21 11:46:07 +00:00
b5d4f2aa74
The mitigation is to not attempt GetObject calls if there have been more than 3 S3 errors in the past minute. The implementation uses the TokenBucket class that we normally use for rate-limiting. An example scenario this is trying to avoid is: * the S3 service becomes unavailable for 10 straight minutes. Each S3 request hangs until we hit the configured timeout (settings.S3_TIMEOUT) * A client is frequently requesting the "Get ping's logged body" API call. Each call causes one webserver process to become busy for S3_TIMEOUT seconds. * All workers become busy, request backlog fills up, our service starts returning 5xx errors. With the mitigation, during an S3 outage, only the calls that retrieve ping's logged body will return 503, the rest of the service will (hopefully) work normally. Fixes: #1114
1346 lines
No EOL
110 KiB
Text
1346 lines
No EOL
110 KiB
Text
<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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/1b9d0386-d07e-44b0-8995-4a9a372de43c.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/1b9d0386-d07e-44b0-8995-4a9a372de43c.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/7d3ab93d-836e-4505-bbda-fcbd5e07adf9.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg"</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">"badge_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"SITE_ROOT/b/2/d43c84db-1502-4d86-a89d-181a33e25896.svg"</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>
|
|
<dt>503 Service Unavailable</dt>
|
|
<dd>External object storage service is unavailable, please try later.</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> |