Browse Source

Add /api/v2/ which reports check's status slightly differently

cc: #633
pull/761/head
Pēteris Caune 1 year ago
parent
commit
4863dda6c3
No known key found for this signature in database GPG Key ID: E28D7679E9A9EDE2
  1. 2
      hc/api/decorators.py
  2. 9
      hc/api/models.py
  3. 18
      hc/api/tests/test_create_check.py
  4. 27
      hc/api/tests/test_delete_check.py
  5. 49
      hc/api/tests/test_get_check.py
  6. 28
      hc/api/tests/test_list_checks.py
  7. 2
      hc/api/tests/test_notify.py
  8. 2
      hc/api/tests/test_notify_sms.py
  9. 2
      hc/api/tests/test_notify_whatsapp.py
  10. 3
      hc/api/tests/test_pause.py
  11. 22
      hc/api/tests/test_update_check.py
  12. 43
      hc/api/urls.py
  13. 17
      hc/api/views.py
  14. 2
      hc/front/management/commands/populate_searchdb.py
  15. 2
      hc/front/views.py
  16. 3
      static/css/docs.css
  17. 167
      templates/docs/api.html
  18. 173
      templates/docs/api.md
  19. 1189
      templates/docs/apiv1.html
  20. 1368
      templates/docs/apiv1.md
  21. 3
      templates/front/docs_single.html

2
hc/api/decorators.py

@ -33,6 +33,7 @@ def authorize(f):
return error("wrong api key", 401)
request.readonly = False
request.v = 2 if request.path_info.startswith("/api/v2/") else 1
return f(request, *args, **kwds)
return wrapper
@ -59,6 +60,7 @@ def authorize_read(f):
return error("wrong api key", 401)
request.readonly = api_key == request.project.api_key_readonly
request.v = 2 if request.path_info.startswith("/api/v2/") else 1
return f(request, *args, **kwds)
return wrapper

9
hc/api/models.py

@ -106,6 +106,7 @@ class CheckDict(TypedDict, total=False):
grace: int
n_pings: int
status: str
started: bool
last_ping: str | None
next_ping: str | None
manual_resume: bool
@ -319,7 +320,8 @@ class Check(models.Model):
code_half = self.code.hex[:16]
return hashlib.sha1(code_half.encode()).hexdigest()
def to_dict(self, readonly=False) -> CheckDict:
def to_dict(self, readonly=False, v=2) -> CheckDict:
with_started = v == 1
result: CheckDict = {
"name": self.name,
"slug": self.slug,
@ -327,7 +329,8 @@ class Check(models.Model):
"desc": self.desc,
"grace": int(self.grace.total_seconds()),
"n_pings": self.n_pings,
"status": self.get_status(with_started=True),
"status": self.get_status(with_started=with_started),
"started": self.last_start is not None,
"last_ping": isostring(self.last_ping),
"next_ping": isostring(self.get_grace_start()),
"manual_resume": self.manual_resume,
@ -350,7 +353,7 @@ class Check(models.Model):
# Optimization: construct API URLs manually instead of using reverse().
# This is significantly quicker when returning hundreds of checks.
update_url = settings.SITE_ROOT + "/api/v1/checks/" + str(self.code)
update_url = settings.SITE_ROOT + f"/api/v{v}/checks/{self.code}"
result["update_url"] = update_url
result["pause_url"] = update_url + "/pause"
result["resume_url"] = update_url + "/resume"

18
hc/api/tests/test_create_check.py

@ -2,6 +2,8 @@ from __future__ import annotations
from datetime import timedelta as td
from django.utils.timezone import now
from hc.api.models import Channel, Check
from hc.test import BaseTestCase
@ -9,11 +11,12 @@ from hc.test import BaseTestCase
class CreateCheckTestCase(BaseTestCase):
URL = "/api/v1/checks/"
def post(self, data, expect_fragment=None):
def post(self, data, expect_fragment=None, v=1):
if "api_key" not in data:
data["api_key"] = "X" * 32
r = self.csrf_client.post(self.URL, data, content_type="application/json")
url = f"/api/v{v}/checks/"
r = self.csrf_client.post(url, data, content_type="application/json")
if expect_fragment:
self.assertEqual(r.status_code, 400)
self.assertIn(expect_fragment, r.json()["error"])
@ -326,3 +329,14 @@ class CreateCheckTestCase(BaseTestCase):
def test_it_rejects_non_string_subject_fail(self):
msg = "subject_fail is not a string"
self.post({"subject_fail": False}, expect_fragment=msg)
def test_v2_reports_started_separately(self):
Check.objects.create(project=self.project, name="X", last_start=now())
r = self.post({"name": "X", "unique": ["name"]}, v=2)
# Expect 200 instead of 201
self.assertEqual(r.status_code, 200)
doc = r.json()
self.assertEqual(doc["status"], "new")
self.assertTrue(doc["started"])

27
hc/api/tests/test_delete_check.py

@ -1,5 +1,7 @@
from __future__ import annotations
from django.utils.timezone import now
from hc.api.models import Check
from hc.test import BaseTestCase
@ -8,7 +10,8 @@ class DeleteCheckTestCase(BaseTestCase):
def setUp(self):
super().setUp()
self.check = Check.objects.create(project=self.project)
self.url = f"/api/v1/checks/{self.check.code}"
self.url = f"/api/v2/checks/{self.check.code}"
self.urlv1 = f"/api/v1/checks/{self.check.code}"
def test_it_works(self):
r = self.client.delete(self.url, HTTP_X_API_KEY="X" * 32)
@ -19,8 +22,8 @@ class DeleteCheckTestCase(BaseTestCase):
self.assertFalse(Check.objects.filter(code=self.check.code).exists())
def test_it_handles_missing_check(self):
url = "/api/v1/checks/07c2f548-9850-4b27-af5d-6c9dc157ec02"
r = self.client.delete(url, HTTP_X_API_KEY="X" * 32)
self.check.delete()
r = self.client.delete(self.url, HTTP_X_API_KEY="X" * 32)
self.assertEqual(r.status_code, 404)
def test_it_handles_options(self):
@ -31,3 +34,21 @@ class DeleteCheckTestCase(BaseTestCase):
def test_it_handles_missing_api_key(self):
r = self.client.delete(self.url)
self.assertContains(r, "missing api key", status_code=401)
def test_v1_reports_status_started(self):
self.check.last_start = now()
self.check.save()
r = self.client.delete(self.urlv1, HTTP_X_API_KEY="X" * 32)
doc = r.json()
self.assertEqual(doc["status"], "started")
self.assertTrue(doc["started"])
def test_v2_reports_started_separately(self):
self.check.last_start = now()
self.check.save()
r = self.client.delete(self.url, HTTP_X_API_KEY="X" * 32)
doc = r.json()
self.assertEqual(doc["status"], "new")
self.assertTrue(doc["started"])

49
hc/api/tests/test_get_check.py

@ -30,8 +30,8 @@ class GetCheckTestCase(BaseTestCase):
self.c1 = Channel.objects.create(project=self.project)
self.a1.channel_set.add(self.c1)
def get(self, code, api_key="X" * 32):
url = "/api/v1/checks/%s" % code
def get(self, code, api_key="X" * 32, v=1):
url = f"/api/v{v}/checks/{code}"
return self.client.get(url, HTTP_X_API_KEY=api_key)
def test_it_works(self):
@ -40,7 +40,7 @@ class GetCheckTestCase(BaseTestCase):
self.assertEqual(r["Access-Control-Allow-Origin"], "*")
doc = r.json()
self.assertEqual(len(doc), 23)
self.assertEqual(len(doc), 24)
self.assertEqual(doc["slug"], "alice-1")
self.assertEqual(doc["timeout"], 3600)
@ -49,6 +49,7 @@ class GetCheckTestCase(BaseTestCase):
self.assertEqual(doc["last_ping"], None)
self.assertEqual(doc["n_pings"], 0)
self.assertEqual(doc["status"], "new")
self.assertFalse(doc["started"])
self.assertEqual(doc["channels"], str(self.c1.code))
self.assertEqual(doc["desc"], "This is description")
self.assertFalse(doc["manual_resume"])
@ -75,7 +76,7 @@ class GetCheckTestCase(BaseTestCase):
self.assertEqual(r["Access-Control-Allow-Origin"], "*")
doc = r.json()
self.assertEqual(len(doc), 23)
self.assertEqual(len(doc), 24)
self.assertEqual(doc["timeout"], 3600)
self.assertEqual(doc["grace"], 900)
@ -100,3 +101,43 @@ class GetCheckTestCase(BaseTestCase):
# When using readonly keys, the ping URLs should not be exposed:
for key in ("ping_url", "update_url", "pause_url", "resume_url"):
self.assertNotContains(r, key)
def test_v1_reports_status_started(self):
self.a1.last_start = now()
self.a1.save()
r = self.get(self.a1.code)
self.assertEqual(r.status_code, 200)
doc = r.json()
self.assertEqual(doc["status"], "started")
self.assertTrue(doc["started"])
def test_v2_reports_started_separately(self):
self.a1.last_start = now()
self.a1.save()
r = self.get(self.a1.code, v=2)
self.assertEqual(r.status_code, 200)
doc = r.json()
self.assertEqual(doc["status"], "new")
self.assertTrue(doc["started"])
def test_v1_by_unique_key_reports_status_started(self):
self.a1.last_start = now()
self.a1.save()
r = self.get(self.a1.unique_key)
doc = r.json()
self.assertEqual(doc["status"], "started")
self.assertTrue(doc["started"])
def test_v2_by_unique_key_reports_started_separately(self):
self.a1.last_start = now()
self.a1.save()
r = self.get(self.a1.unique_key, v=2)
doc = r.json()
self.assertEqual(doc["status"], "new")
self.assertTrue(doc["started"])

28
hc/api/tests/test_list_checks.py

@ -35,8 +35,8 @@ class ListChecksTestCase(BaseTestCase):
self.c1 = Channel.objects.create(project=self.project)
self.a1.channel_set.add(self.c1)
def get(self):
return self.client.get("/api/v1/checks/", HTTP_X_API_KEY="X" * 32)
def get(self, v=1):
return self.client.get(f"/api/v{v}/checks/", HTTP_X_API_KEY="X" * 32)
def test_it_works(self):
# Expect 3 queries:
@ -63,6 +63,7 @@ class ListChecksTestCase(BaseTestCase):
self.assertEqual(a1["last_ping"], None)
self.assertEqual(a1["n_pings"], 0)
self.assertEqual(a1["status"], "new")
self.assertFalse(a1["started"])
self.assertEqual(a1["channels"], str(self.c1.code))
self.assertEqual(a1["desc"], "This is description")
@ -155,3 +156,26 @@ class ListChecksTestCase(BaseTestCase):
# When using readonly keys, the ping URLs should not be exposed:
self.assertNotContains(r, self.a1.url())
def test_v1_reports_status_started(self):
self.a1.last_start = now()
self.a1.save()
self.a2.delete()
r = self.get()
self.assertEqual(r.status_code, 200)
a1 = r.json()["checks"][0]
self.assertEqual(a1["status"], "started")
self.assertTrue(a1["started"])
def test_v2_reports_started_separately(self):
self.a1.last_start = now()
self.a1.save()
self.a2.delete()
r = self.get(v=2)
a1 = r.json()["checks"][0]
self.assertEqual(a1["status"], "new")
self.assertTrue(a1["started"])

2
hc/api/tests/test_notify.py

@ -62,7 +62,7 @@ class NotifyTestCase(BaseTestCase):
self.assertEqual(payload["To"], "+1234567890")
n = Notification.objects.get()
callback_path = f"/api/v1/notifications/{n.code}/status"
callback_path = f"/api/v2/notifications/{n.code}/status"
self.assertTrue(payload["StatusCallback"].endswith(callback_path))
@patch("hc.api.transports.curl.request")

2
hc/api/tests/test_notify_sms.py

@ -42,7 +42,7 @@ class NotifySmsTestCase(BaseTestCase):
self.assertIn("is DOWN", payload["Body"])
n = Notification.objects.get()
callback_path = f"/api/v1/notifications/{n.code}/status"
callback_path = f"/api/v2/notifications/{n.code}/status"
self.assertTrue(payload["StatusCallback"].endswith(callback_path))
# sent SMS counter should go up

2
hc/api/tests/test_notify_whatsapp.py

@ -39,7 +39,7 @@ class NotifyWhatsAppTestCase(BaseTestCase):
self.assertEqual(payload["To"], "whatsapp:+1234567890")
n = Notification.objects.get()
callback_path = f"/api/v1/notifications/{n.code}/status"
callback_path = f"/api/v2/notifications/{n.code}/status"
self.assertTrue(payload["StatusCallback"].endswith(callback_path))
# sent SMS counter should go up

3
hc/api/tests/test_pause.py

@ -13,7 +13,8 @@ class PauseTestCase(BaseTestCase):
super().setUp()
self.check = Check.objects.create(project=self.project, status="up")
self.url = f"/api/v1/checks/{self.check.code}/pause"
self.url = f"/api/v2/checks/{self.check.code}/pause"
self.urlv1 = f"/api/v2/checks/{self.check.code}/pause"
def test_it_works(self):
r = self.csrf_client.post(

22
hc/api/tests/test_update_check.py

@ -14,8 +14,8 @@ class UpdateCheckTestCase(BaseTestCase):
super().setUp()
self.check = Check.objects.create(project=self.project)
def post(self, code, data):
url = "/api/v1/checks/%s" % code
def post(self, code, data, v=1):
url = f"/api/v{v}/checks/{code}"
return self.csrf_client.post(url, data, content_type="application/json")
def test_it_works(self):
@ -380,3 +380,21 @@ class UpdateCheckTestCase(BaseTestCase):
self.check.refresh_from_db()
self.assertFalse(self.check.filter_subject)
self.assertEqual(self.check.success_kw, "SUCCESS")
def test_v1_reports_status_started(self):
self.check.last_start = now()
self.check.save()
r = self.post(self.check.code, {"api_key": "X" * 32})
doc = r.json()
self.assertEqual(doc["status"], "started")
self.assertTrue(doc["started"])
def test_v2_reports_started_separately(self):
self.check.last_start = now()
self.check.save()
r = self.post(self.check.code, {"api_key": "X" * 32}, v=2)
doc = r.json()
self.assertEqual(doc["status"], "new")
self.assertTrue(doc["started"])

43
hc/api/urls.py

@ -45,31 +45,38 @@ slug_urls = [
path("<int:exitstatus>", views.ping_by_slug),
]
urlpatterns = [
path("ping/<uuid:code>", views.ping),
path("ping/<uuid:code>/", include(uuid_urls)),
path("ping/<slug:ping_key>/<slug:slug>", views.ping_by_slug),
path("ping/<slug:ping_key>/<slug:slug>/", include(slug_urls)),
path("api/v1/checks/", views.checks),
path("api/v1/checks/<uuid:code>", views.single, name="hc-api-single"),
path("api/v1/checks/<sha1:unique_key>", views.get_check_by_unique_key),
path("api/v1/checks/<uuid:code>/pause", views.pause, name="hc-api-pause"),
path("api/v1/checks/<uuid:code>/resume", views.resume, name="hc-api-resume"),
api_urls = [
path("checks/", views.checks),
path("checks/<uuid:code>", views.single, name="hc-api-single"),
path("checks/<sha1:unique_key>", views.get_check_by_unique_key),
path("checks/<uuid:code>/pause", views.pause, name="hc-api-pause"),
path("checks/<uuid:code>/resume", views.resume, name="hc-api-resume"),
path(
"api/v1/notifications/<uuid:code>/status",
"notifications/<uuid:code>/status",
views.notification_status,
name="hc-api-notification-status",
),
path("api/v1/checks/<uuid:code>/pings/", views.pings, name="hc-api-pings"),
path("checks/<uuid:code>/pings/", views.pings, name="hc-api-pings"),
path(
"api/v1/checks/<uuid:code>/pings/<int:n>/body",
"checks/<uuid:code>/pings/<int:n>/body",
views.ping_body,
name="hc-api-ping-body",
),
path("api/v1/checks/<uuid:code>/flips/", views.flips_by_uuid, name="hc-api-flips"),
path("api/v1/checks/<sha1:unique_key>/flips/", views.flips_by_unique_key),
path("api/v1/channels/", views.channels),
path("api/v1/badges/", views.badges),
path("checks/<uuid:code>/flips/", views.flips_by_uuid, name="hc-api-flips"),
path("checks/<sha1:unique_key>/flips/", views.flips_by_unique_key),
path("channels/", views.channels),
path("badges/", views.badges),
path("metrics/", views.metrics),
path("status/", views.status),
]
urlpatterns = [
path("ping/<uuid:code>", views.ping),
path("ping/<uuid:code>/", include(uuid_urls)),
path("ping/<slug:ping_key>/<slug:slug>", views.ping_by_slug),
path("ping/<slug:ping_key>/<slug:slug>/", include(slug_urls)),
path("api/v1/", include(api_urls)),
path("api/v2/", include(api_urls)),
path(
"badge/<slug:badge_key>/<slug:signature>/<quoted:tag>.<slug:fmt>",
views.badge,
@ -81,6 +88,4 @@ urlpatterns = [
{"tag": "*"},
name="hc-badge-all",
),
path("api/v1/metrics/", views.metrics),
path("api/v1/status/", views.status),
]

17
hc/api/views.py

@ -232,7 +232,7 @@ def get_checks(request):
for check in q:
# precise, final filtering
if not tags or check.matches_tag_set(tags):
checks.append(check.to_dict(readonly=request.readonly))
checks.append(check.to_dict(readonly=request.readonly, v=request.v))
return JsonResponse({"checks": checks})
@ -254,7 +254,7 @@ def create_check(request):
except BadChannelException as e:
return JsonResponse({"error": e.message}, status=400)
return JsonResponse(check.to_dict(), status=201 if created else 200)
return JsonResponse(check.to_dict(v=request.v), status=201 if created else 200)
@csrf_exempt
@ -280,7 +280,8 @@ def get_check(request, code):
check = get_object_or_404(Check, code=code)
if check.project_id != request.project.id:
return HttpResponseForbidden()
return JsonResponse(check.to_dict(readonly=request.readonly))
return JsonResponse(check.to_dict(readonly=request.readonly, v=request.v))
@cors("GET")
@ -290,7 +291,7 @@ def get_check_by_unique_key(request, unique_key):
checks = Check.objects.filter(project=request.project.id)
for check in checks:
if check.unique_key == unique_key:
return JsonResponse(check.to_dict(readonly=request.readonly))
return JsonResponse(check.to_dict(readonly=request.readonly, v=request.v))
return HttpResponseNotFound()
@ -306,7 +307,7 @@ def update_check(request, code):
except BadChannelException as e:
return JsonResponse({"error": e.message}, status=400)
return JsonResponse(check.to_dict())
return JsonResponse(check.to_dict(v=request.v))
@authorize
@ -315,7 +316,7 @@ def delete_check(request, code):
if check.project_id != request.project.id:
return HttpResponseForbidden()
response = check.to_dict()
response = check.to_dict(v=request.v)
check.delete()
return JsonResponse(response)
@ -353,7 +354,7 @@ def pause(request, code):
# and Profile.next_nag_date needs to be cleared out:
check.project.update_next_nag_dates()
return JsonResponse(check.to_dict())
return JsonResponse(check.to_dict(v=request.v))
@cors("POST")
@ -376,7 +377,7 @@ def resume(request, code):
check.alert_after = None
check.save()
return JsonResponse(check.to_dict())
return JsonResponse(check.to_dict(v=request.v))
@cors("GET")

2
hc/front/management/commands/populate_searchdb.py

@ -25,6 +25,8 @@ class Command(BaseCommand):
for filename in os.listdir(docs_path):
if not filename.endswith(".html"):
continue
if filename == "apiv1.md":
continue
slug = filename[:-5] # cut ".html"
print("Processing %s" % slug)

2
hc/front/views.py

@ -383,7 +383,7 @@ def _replace_placeholders(doc, html):
def serve_doc(request, doc="introduction"):
# Filenames in /templates/docs/ consist of lowercase letters and underscores,
# -- make sure we don't accept anything else
if not re.match(r"^[a-z_]+$", doc):
if not re.match(r"^[0-9a-z_]+$", doc):
raise Http404("not found")
path = os.path.join(settings.BASE_DIR, "templates/docs", doc + ".html")

3
static/css/docs.css

@ -82,17 +82,20 @@ h2.rule {
}
.docs-api table,
.docs-apiv1 table,
.docs-http_api table {
width: 100%;
margin: 8px 0;
}
.docs-api th,
.docs-apiv1 th,
.docs-http_api th {
display: none;
}
.docs-api td,
.docs-apiv1 td,
.docs-http_api td {
padding: 8px;
border: 1px solid var(--border-color);

167
templates/docs/api.html

@ -1,4 +1,4 @@
<h1>Management API</h1>
<h1>Management API v2</h1>
<p>With the Management API, you can programmatically manage checks and integrations
in your account.</p>
<h2>API Endpoints</h2>
@ -16,31 +16,31 @@ in your account.</p>
</tr>
<tr>
<td><a href="#list-checks">List existing checks</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/</code></td>
<td><code>GET SITE_ROOT/api/v2/checks/</code></td>
</tr>
<tr>
<td><a href="#get-check">Get a single check</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code><br><code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;</code></td>
<td><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;</code><br><code>GET SITE_ROOT/api/v2/checks/&lt;unique_key&gt;</code></td>
</tr>
<tr>
<td><a href="#create-check">Create a new check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/</code></td>
<td><code>POST SITE_ROOT/api/v2/checks/</code></td>
</tr>
<tr>
<td><a href="#update-check">Update an existing check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></td>
<td><code>POST SITE_ROOT/api/v2/checks/&lt;uuid&gt;</code></td>
</tr>
<tr>
<td><a href="#pause-check">Pause monitoring of a check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pause</code></td>
<td><code>POST SITE_ROOT/api/v2/checks/&lt;uuid&gt;/pause</code></td>
</tr>
<tr>
<td><a href="#resume-check">Resume monitoring of a check</a></td>
<td><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;/resume</code></td>
<td><code>POST SITE_ROOT/api/v2/checks/&lt;uuid&gt;/resume</code></td>
</tr>
<tr>
<td><a href="#delete-check">Delete check</a></td>
<td><code>DELETE SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></td>
<td><code>DELETE SITE_ROOT/api/v2/checks/&lt;uuid&gt;</code></td>
</tr>
<tr>
<td><strong>Pings</strong></td>
@ -48,11 +48,11 @@ in your account.</p>
</tr>
<tr>
<td><a href="#list-pings">List check's logged pings</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/</code></td>
<td><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;/pings/</code></td>
</tr>
<tr>
<td><a href="#ping-body">Get a ping's logged body</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/&lt;n&gt;/body</code></td>
<td><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;/pings/&lt;n&gt;/body</code></td>
</tr>
<tr>
<td><strong>Flips</strong></td>
@ -60,7 +60,7 @@ in your account.</p>
</tr>
<tr>
<td><a href="#list-flips">List check's status changes</a></td>
<td><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/flips/</code><br><code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;/flips/</code></td>
<td><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;/flips/</code><br><code>GET SITE_ROOT/api/v2/checks/&lt;unique_key&gt;/flips/</code></td>
</tr>
<tr>
<td><strong>Integrations</strong></td>
@ -68,7 +68,7 @@ in your account.</p>
</tr>
<tr>
<td><a href="#list-channels">List existing integrations</a></td>
<td><code>GET SITE_ROOT/api/v1/channels/</code></td>
<td><code>GET SITE_ROOT/api/v2/channels/</code></td>
</tr>
<tr>
<td><strong>Badges</strong></td>
@ -76,10 +76,24 @@ in your account.</p>
</tr>
<tr>
<td><a href="#list-badges">List project's badges</a></td>
<td><code>GET SITE_ROOT/api/v1/badges/</code></td>
<td><code>GET SITE_ROOT/api/v2/badges/</code></td>
</tr>
</tbody>
</table>
<h2>Changes From v1</h2>
<p>Management API v2 changes the status reporting of checks in started state.
If a check is running, API v1 reports its status as <code>started</code>. API v2 instead reports
the started state in a separate <code>started</code> boolean field. It can therefore
express "up and currently running" and "down, but currently running" states.</p>
<p>For example, if a check is down, but also has recently received a <code>/start</code> signal,
Management API v1 would report its status as:</p>
<div class="highlight"><pre><span></span><code>{&quot;status&quot;: &quot;started&quot;, ...}
</code></pre></div>
<p>Management API v2 would report its status as:</p>
<div class="highlight"><pre><span></span><code>{&quot;status&quot;: &quot;down&quot;, &quot;started&quot;: true, ...}
</code></pre></div>
<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.
@ -114,7 +128,7 @@ 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/v1/checks/</code></p>
<p><code>GET SITE_ROOT/api/v2/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>
@ -125,7 +139,7 @@ one or more tags.</p>
specified value.</p>
<p>This parameter can be repeated multiple times.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/?tag=foo&amp;tag=bar</code></p>
<p><code>SITE_ROOT/api/v2/checks/?tag=foo&amp;tag=bar</code></p>
</dd>
</dl>
<h3>Response Codes</h3>
@ -136,7 +150,7 @@ specified value.</p>
<dd>The API key is either missing or invalid.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/checks/
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v2/checks/
</code></pre></div>
<h3>Example Response</h3>
@ -150,6 +164,7 @@ specified value.</p>
<span class="w"> </span><span class="nt">&quot;grace&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;n_pings&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;up&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;last_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-24T14:02:03+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;next_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-24T15:02:03+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
@ -159,9 +174,9 @@ specified value.</p>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINT31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/31365bce-8da9-4729-8ff3-aaa71d56b712&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;channels&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;timeout&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span><span class="w"></span>
<span class="w"> </span><span class="p">},</span><span class="w"></span>
@ -173,6 +188,7 @@ specified value.</p>
<span class="w"> </span><span class="nt">&quot;grace&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;n_pings&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;down&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;last_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;next_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
@ -182,9 +198,9 @@ specified value.</p>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;channels&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;schedule&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tz&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;UTC&quot;</span><span class="w"></span>
@ -193,7 +209,7 @@ specified value.</p>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<p>The possible values for the <code>status</code> field are: <code>new</code>, <code>started</code>, <code>up</code>, <code>grace</code>, <code>down</code>,
<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>ping_url</code>, <code>update_url</code>, <code>pause_url</code>, <code>resume_url</code>, <code>channels</code>. It adds an extra
@ -211,6 +227,7 @@ and <a href="#list-flips">List check's status changes</a> API calls.</p>
<span class="w"> </span><span class="nt">&quot;grace&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;n_pings&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;up&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;last_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-24T14:02:03+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;next_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-24T15:02:03+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
@ -230,6 +247,7 @@ and <a href="#list-flips">List check's status changes</a> API calls.</p>
<span class="w"> </span><span class="nt">&quot;grace&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;n_pings&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;down&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;last_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;next_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
@ -247,8 +265,8 @@ and <a href="#list-flips">List check's status changes</a> API calls.</p>
</code></pre></div>
<h2 class="rule" id="get-check">Get a Single Check</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code><br>
<code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;</code></p>
<p><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;</code><br>
<code>GET SITE_ROOT/api/v2/checks/&lt;unique_key&gt;</code></p>
<p>Returns a JSON representation of a single check. Accepts either check's UUID or
the <code>unique_key</code> (a field derived from UUID and returned by API responses when
using the read-only API key) as an identifier.</p>
@ -264,7 +282,7 @@ using the read-only API key) as an identifier.</p>
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/checks/&lt;uuid&gt;
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v2/checks/&lt;uuid&gt;
</code></pre></div>
<h3>Example Response</h3>
@ -276,6 +294,7 @@ using the read-only API key) as an identifier.</p>
<span class="w"> </span><span class="nt">&quot;grace&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;n_pings&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;down&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;last_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;next_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
@ -285,16 +304,16 @@ using the read-only API key) as an identifier.</p>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;channels&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;schedule&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;15 5 * * *&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tz&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;UTC&quot;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<p>The possible values for the <code>status</code> field are: <code>new</code>, <code>started</code>, <code>up</code>, <code>grace</code>, <code>down</code>,
<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:
@ -310,6 +329,7 @@ easily construct these URLs themselves <em>if</em> they know the check's unique
<span class="w"> </span><span class="nt">&quot;grace&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">1200</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;n_pings&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">7</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;down&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;last_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;2020-03-23T10:19:32+00:00&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;next_ping&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;manual_resume&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
@ -325,7 +345,7 @@ easily construct these URLs themselves <em>if</em> they know the check's unique
</code></pre></div>
<h2 class="rule" id="create-check">Create a Check</h2>
<p><code>POST SITE_ROOT/api/v1/checks/</code></p>
<p><code>POST SITE_ROOT/api/v2/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>
@ -528,13 +548,13 @@ field values.</dd>
the limit is 20 checks per account.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/ <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> <span class="se">\</span>
--data <span class="s1">&#39;{&quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
<p>Or, alternatively:</p>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/ <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/ <span class="se">\</span>
--data <span class="s1">&#39;{&quot;api_key&quot;: &quot;your-api-key&quot;, &quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
@ -554,18 +574,19 @@ the limit is 20 checks per account.</dd>
<span class="w"> </span><span class="nt">&quot;failure_kw&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;new&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tags&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;prod www&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;timeout&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="update-check">Update an Existing Check</h2>
<p><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></p>
<p><code>POST SITE_ROOT/api/v2/checks/&lt;uuid&gt;</code></p>
<p>Updates an existing check. All request parameters are optional. If you omit any
parameter, SITE_NAME will leave its value unchanged.</p>
<h3>Request Parameters</h3>
@ -746,13 +767,13 @@ field values.</dd>
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> <span class="se">\</span>
--data <span class="s1">&#39;{&quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
<p>Or, alternatively:</p>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
--data <span class="s1">&#39;{&quot;api_key&quot;: &quot;your-api-key&quot;, &quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
</code></pre></div>
@ -772,18 +793,19 @@ field values.</dd>
<span class="w"> </span><span class="nt">&quot;failure_kw&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;new&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tags&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;prod www&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;timeout&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="pause-check">Pause Monitoring of a Check</h2>
<p><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pause</code></p>
<p><code>POST SITE_ROOT/api/v2/checks/&lt;uuid&gt;/pause</code></p>
<p>Disables monitoring for a check without removing it. The check goes into a "paused"
state. You can resume monitoring of the check by pinging it, or by running
the <a href="#resume-check">Resume</a> API call (useful when check's <code>manual_resume=True</code>).</p>
@ -800,7 +822,7 @@ the <a href="#resume-check">Resume</a> API call (useful when check's <code>manua
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause <span class="se">\</span>
--request POST --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> --data <span class="s2">&quot;&quot;</span>
</code></pre></div>
@ -824,18 +846,19 @@ header is sometimes required by some network proxies and web servers.</p>
<span class="w"> </span><span class="nt">&quot;failure_kw&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;paused&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tags&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;prod www&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;timeout&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="resume-check">Resume Monitoring of a Check</h2>
<p><code>POST SITE_ROOT/api/v1/checks/&lt;uuid&gt;/resume</code></p>
<p><code>POST SITE_ROOT/api/v2/checks/&lt;uuid&gt;/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>
@ -854,7 +877,7 @@ configuration parameter set to <code>True</code>.</p>
<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 SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/resume <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/resume <span class="se">\</span>
--request POST --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> --data <span class="s2">&quot;&quot;</span>
</code></pre></div>
@ -878,18 +901,19 @@ header is sometimes required by some network proxies and web servers.</p>
<span class="w"> </span><span class="nt">&quot;failure_kw&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;new&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tags&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;prod www&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;timeout&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="delete-check">Delete Check</h2>
<p><code>DELETE SITE_ROOT/api/v1/checks/&lt;uuid&gt;</code></p>
<p><code>DELETE SITE_ROOT/api/v2/checks/&lt;uuid&gt;</code></p>
<p>Permanently deletes the check from the user's account. Returns JSON representation of the
check that was just deleted.</p>
<p>This API call has no request parameters.</p>
@ -905,7 +929,7 @@ check that was just deleted.</p>
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc <span class="se">\</span>
--request DELETE --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
@ -925,18 +949,19 @@ check that was just deleted.</p>
<span class="w"> </span><span class="nt">&quot;failure_kw&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_subject&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;filter_body&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;pause_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;resume_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;ping_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;new&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;started&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;tags&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;prod www&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;timeout&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">3600</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;update_url&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc&quot;</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<h2 class="rule" id="list-pings">List check's logged pings</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/</code></p>
<p><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;/pings/</code></p>
<p>Returns a list of pings this check has received.</p>
<p>This endpoint returns pings in reverse order (most recent first), and the total
number of returned pings depends on the account's billing plan: 100 for free accounts,
@ -953,7 +978,7 @@ number of returned pings depends on the account's billing plan: 100 for free acc
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
@ -1011,7 +1036,7 @@ number of returned pings depends on the account's billing plan: 100 for free acc
</code></pre></div>
<h2 class="rule" id="ping-body">Get a ping's logged body</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/pings/&lt;n&gt;/body</code></p>
<p><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;/pings/&lt;n&gt;/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>
@ -1024,13 +1049,13 @@ response header, and the ping body is returned verbatim in the response body.</p
<dd>The check does not exist, the ping does not exist, or the ping has no body data.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
<h2 class="rule" id="list-flips">List check's status changes</h2>
<p><code>GET SITE_ROOT/api/v1/checks/&lt;uuid&gt;/flips/</code><br>
<code>GET SITE_ROOT/api/v1/checks/&lt;unique_key&gt;/flips/</code></p>
<p><code>GET SITE_ROOT/api/v2/checks/&lt;uuid&gt;/flips/</code><br>
<code>GET SITE_ROOT/api/v2/checks/&lt;unique_key&gt;/flips/</code></p>
<p>Returns a list of "flips" this check has experienced. A flip is a change of status
(from "down" to "up," or from "up" to "down").</p>
<h3>Query Parameters</h3>
@ -1039,19 +1064,19 @@ response header, and the ping body is returned verbatim in the response body.</p
<dd>
<p>Returns the flips from the last <code>value</code> seconds</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?seconds=3600</code></p>
<p><code>SITE_ROOT/api/v2/checks/&lt;uuid|unique_key&gt;/flips/?seconds=3600</code></p>
</dd>
<dt>start=&lt;value&gt;</dt>
<dd>
<p>Returns flips that are newer than the specified UNIX timestamp.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?start=1592214380</code></p>
<p><code>SITE_ROOT/api/v2/checks/&lt;uuid|unique_key&gt;/flips/?start=1592214380</code></p>
</dd>
<dt>end=&lt;value&gt;</dt>
<dd>
<p>Returns flips that are older than the specified UNIX timestamp.</p>
<p>Example:</p>
<p><code>SITE_ROOT/api/v1/checks/&lt;uuid|unique_key&gt;/flips/?end=1592217980</code></p>
<p><code>SITE_ROOT/api/v2/checks/&lt;uuid|unique_key&gt;/flips/?end=1592217980</code></p>
</dd>
</dl>
<h3>Response Codes</h3>
@ -1068,7 +1093,7 @@ response header, and the ping body is returned verbatim in the response body.</p
<dd>The specified check does not exist.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ <span class="se">\</span>
<div class="highlight"><pre><span></span><code>curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ <span class="se">\</span>
--header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span>
</code></pre></div>
@ -1090,7 +1115,7 @@ response header, and the ping body is returned verbatim in the response body.</p
</code></pre></div>
<h2 class="rule" id="list-channels">List Existing Integrations</h2>
<p><code>GET SITE_ROOT/api/v1/channels/</code></p>
<p><code>GET SITE_ROOT/api/v2/channels/</code></p>
<p>Returns a list of integrations belonging to the project.</p>
<h3>Response Codes</h3>
<dl>
@ -1100,7 +1125,7 @@ response header, and the ping body is returned verbatim in the response body.</p
<dd>The API key is either missing or invalid.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/channels/
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v2/channels/
</code></pre></div>
<h3>Example Response</h3>
@ -1121,7 +1146,7 @@ response header, and the ping body is returned verbatim in the response body.</p
</code></pre></div>
<h2 class="rule" id="list-badges">List Project's Badges</h2>
<p><code>GET SITE_ROOT/api/v1/badges/</code></p>
<p><code>GET SITE_ROOT/api/v2/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>
@ -1146,7 +1171,7 @@ of all checks in the project.</p>
<dd>The API key is either missing or invalid.</dd>
</dl>
<h3>Example Request</h3>
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v1/badges/
<div class="highlight"><pre><span></span><code>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> SITE_ROOT/api/v2/badges/
</code></pre></div>
<h3>Example Response</h3>

173
templates/docs/api.md

@ -1,4 +1,4 @@
# Management API
# Management API v2
With the Management API, you can programmatically manage checks and integrations
in your account.
@ -8,22 +8,42 @@ in your account.
Endpoint Name | Endpoint Address
------------------------------------------------------|-------
**Checks**|
[List existing checks](#list-checks) | `GET SITE_ROOT/api/v1/checks/`
[Get a single check](#get-check) | `GET SITE_ROOT/api/v1/checks/<uuid>`<br>`GET SITE_ROOT/api/v1/checks/<unique_key>`
[Create a new check](#create-check) | `POST SITE_ROOT/api/v1/checks/`
[Update an existing check](#update-check) | `POST SITE_ROOT/api/v1/checks/<uuid>`
[Pause monitoring of a check](#pause-check) | `POST SITE_ROOT/api/v1/checks/<uuid>/pause`
[Resume monitoring of a check](#resume-check) | `POST SITE_ROOT/api/v1/checks/<uuid>/resume`
[Delete check](#delete-check) | `DELETE SITE_ROOT/api/v1/checks/<uuid>`
[List existing checks](#list-checks) | `GET SITE_ROOT/api/v2/checks/`
[Get a single check](#get-check) | `GET SITE_ROOT/api/v2/checks/<uuid>`<br>`GET SITE_ROOT/api/v2/checks/<unique_key>`
[Create a new check](#create-check) | `POST SITE_ROOT/api/v2/checks/`
[Update an existing check](#update-check) | `POST SITE_ROOT/api/v2/checks/<uuid>`
[Pause monitoring of a check](#pause-check) | `POST SITE_ROOT/api/v2/checks/<uuid>/pause`
[Resume monitoring of a check](#resume-check) | `POST SITE_ROOT/api/v2/checks/<uuid>/resume`
[Delete check](#delete-check) | `DELETE SITE_ROOT/api/v2/checks/<uuid>`
**Pings**|
[List check's logged pings](#list-pings) | `GET SITE_ROOT/api/v1/checks/<uuid>/pings/`
[Get a ping's logged body](#ping-body) | `GET SITE_ROOT/api/v1/checks/<uuid>/pings/<n>/body`
[List check's logged pings](#list-pings) | `GET SITE_ROOT/api/v2/checks/<uuid>/pings/`
[Get a ping's logged body](#ping-body) | `GET SITE_ROOT/api/v2/checks/<uuid>/pings/<n>/body`
**Flips**|
[List check's status changes](#list-flips) | `GET SITE_ROOT/api/v1/checks/<uuid>/flips/`<br>`GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
[List check's status changes](#list-flips) | `GET SITE_ROOT/api/v2/checks/<uuid>/flips/`<br>`GET SITE_ROOT/api/v2/checks/<unique_key>/flips/`
**Integrations**|
[List existing integrations](#list-channels) | `GET SITE_ROOT/api/v1/channels/`
[List existing integrations](#list-channels) | `GET SITE_ROOT/api/v2/channels/`
**Badges**|
[List project's badges](#list-badges) | `GET SITE_ROOT/api/v1/badges/`
[List project's badges](#list-badges) | `GET SITE_ROOT/api/v2/badges/`
## Changes From v1
Management API v2 changes the status reporting of checks in started state.
If a check is running, API v1 reports its status as `started`. API v2 instead reports
the started state in a separate `started` boolean field. It can therefore
express "up and currently running" and "down, but currently running" states.
For example, if a check is down, but also has recently received a `/start` signal,
Management API v1 would report its status as:
```
{"status": "started", ...}
```
Management API v2 would report its status as:
```
{"status": "down", "started": true, ...}
```
## Authentication
@ -66,7 +86,7 @@ The response may contain a JSON document with additional data.
## List Existing Checks {: #list-checks .rule }
`GET SITE_ROOT/api/v1/checks/`
`GET SITE_ROOT/api/v2/checks/`
Returns a list of checks belonging to the user, optionally filtered by
one or more tags.
@ -81,7 +101,7 @@ tag=&lt;value&gt;
Example:
`SITE_ROOT/api/v1/checks/?tag=foo&tag=bar`
`SITE_ROOT/api/v2/checks/?tag=foo&tag=bar`
### Response Codes
@ -94,7 +114,7 @@ tag=&lt;value&gt;
### Example Request
```bash
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v2/checks/
```
### Example Response
@ -110,6 +130,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
"grace": 600,
"n_pings": 1,
"status": "up",
"started": false,
"last_ping": "2020-03-24T14:02:03+00:00",
"next_ping": "2020-03-24T15:02:03+00:00",
"manual_resume": false,
@ -119,9 +140,9 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
"filter_subject": true,
"filter_body": false,
"ping_url": "PING_ENDPOINT31365bce-8da9-4729-8ff3-aaa71d56b712",
"update_url": "SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712",
"pause_url": "SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause",
"resume_url": "SITE_ROOT/api/v1/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume",
"update_url": "SITE_ROOT/api/v2/checks/31365bce-8da9-4729-8ff3-aaa71d56b712",
"pause_url": "SITE_ROOT/api/v2/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause",
"resume_url": "SITE_ROOT/api/v2/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume",
"channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
"timeout": 3600
},
@ -133,6 +154,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
@ -142,9 +164,9 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
"filter_subject": false,
"filter_body": false,
"ping_url": "PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d",
"update_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
"pause_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
"resume_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
"update_url": "SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
"pause_url": "SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
"resume_url": "SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
"channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
"schedule": "15 5 * * *",
"tz": "UTC"
@ -153,7 +175,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/
}
```
The possible values for the `status` field are: `new`, `started`, `up`, `grace`, `down`,
The possible values for the `status` field are: `new`, `up`, `grace`, `down`,
and `paused`.
When using the read-only API key, SITE_NAME omits the following fields from responses:
@ -175,6 +197,7 @@ Example:
"grace": 600,
"n_pings": 1,
"status": "up",
"started": false,
"last_ping": "2020-03-24T14:02:03+00:00",
"next_ping": "2020-03-24T15:02:03+00:00",
"manual_resume": false,
@ -194,6 +217,7 @@ Example:
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
@ -211,8 +235,8 @@ Example:
```
## Get a Single Check {: #get-check .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>`<br>
`GET SITE_ROOT/api/v1/checks/<unique_key>`
`GET SITE_ROOT/api/v2/checks/<uuid>`<br>
`GET SITE_ROOT/api/v2/checks/<unique_key>`
Returns a JSON representation of a single check. Accepts either check's UUID or
the `unique_key` (a field derived from UUID and returned by API responses when
@ -236,7 +260,7 @@ using the read-only API key) as an identifier.
### Example Request
```bash
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/<uuid>
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v2/checks/<uuid>
```
### Example Response
@ -250,6 +274,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/<uuid>
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
@ -259,16 +284,16 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/<uuid>
"filter_subject": true,
"filter_body": false,
"ping_url": "PING_ENDPOINT803f680d-e89b-492b-82ef-2be7b774a92d",
"update_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
"pause_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
"resume_url": "SITE_ROOT/api/v1/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
"update_url": "SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
"pause_url": "SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
"resume_url": "SITE_ROOT/api/v2/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
"channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
"schedule": "15 5 * * *",
"tz": "UTC"
}
```
The possible values for the `status` field are: `new`, `started`, `up`, `grace`, `down`,
The possible values for the `status` field are: `new`, `up`, `grace`, `down`,
and `paused`.
### Example Read-Only Response
@ -289,6 +314,7 @@ easily construct these URLs themselves *if* they know the check's unique UUID.
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
@ -305,7 +331,7 @@ easily construct these URLs themselves *if* they know the check's unique UUID.
## Create a Check {: #create-check .rule }
`POST SITE_ROOT/api/v1/checks/`
`POST SITE_ROOT/api/v2/checks/`
Creates a new check and returns its ping URL.
All request parameters are optional and will use their default
@ -561,7 +587,7 @@ subject_fail
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/ \
curl SITE_ROOT/api/v2/checks/ \
--header "X-Api-Key: your-api-key" \
--data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
```
@ -569,7 +595,7 @@ curl SITE_ROOT/api/v1/checks/ \
Or, alternatively:
```bash
curl SITE_ROOT/api/v1/checks/ \
curl SITE_ROOT/api/v2/checks/ \
--data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
```
@ -591,19 +617,20 @@ curl SITE_ROOT/api/v1/checks/ \
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"pause_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
"status": "new",
"started": false,
"tags": "prod www",
"timeout": 3600,
"update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
"update_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
}
```
## Update an Existing Check {: #update-check .rule }
`POST SITE_ROOT/api/v1/checks/<uuid>`
`POST SITE_ROOT/api/v2/checks/<uuid>`
Updates an existing check. All request parameters are optional. If you omit any
parameter, SITE_NAME will leave its value unchanged.
@ -834,7 +861,7 @@ subject_fail
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
--header "X-Api-Key: your-api-key" \
--data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
```
@ -842,7 +869,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
Or, alternatively:
```bash
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
--data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
```
@ -864,19 +891,20 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"pause_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
"status": "new",
"started": false,
"tags": "prod www",
"timeout": 3600,
"update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
"update_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
}
```
## Pause Monitoring of a Check {: #pause-check .rule }
`POST SITE_ROOT/api/v1/checks/<uuid>/pause`
`POST SITE_ROOT/api/v2/checks/<uuid>/pause`
Disables monitoring for a check without removing it. The check goes into a "paused"
state. You can resume monitoring of the check by pinging it, or by running
@ -901,7 +929,7 @@ This API call has no request parameters.
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \
curl SITE_ROOT/api/v2/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/pause \
--request POST --header "X-Api-Key: your-api-key" --data ""
```
@ -928,19 +956,20 @@ header is sometimes required by some network proxies and web servers.
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"pause_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
"status": "paused",
"started": false,
"tags": "prod www",
"timeout": 3600,
"update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc"
"update_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc"
}
```
## Resume Monitoring of a Check {: #resume-check .rule }
`POST SITE_ROOT/api/v1/checks/<uuid>/resume`
`POST SITE_ROOT/api/v2/checks/<uuid>/resume`
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 `manual_resume`
@ -968,7 +997,7 @@ This API call has no request parameters.
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/resume \
curl SITE_ROOT/api/v2/checks/0c8983c9-9d73-446f-adb5-0641fdacc9d4/resume \
--request POST --header "X-Api-Key: your-api-key" --data ""
```
@ -995,20 +1024,21 @@ header is sometimes required by some network proxies and web servers.
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"pause_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
"status": "new",
"started": false,
"tags": "prod www",
"timeout": 3600,
"update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc"
"update_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc"
}
```
## Delete Check {: #delete-check .rule }
`DELETE SITE_ROOT/api/v1/checks/<uuid>`
`DELETE SITE_ROOT/api/v2/checks/<uuid>`
Permanently deletes the check from the user's account. Returns JSON representation of the
check that was just deleted.
@ -1032,7 +1062,7 @@ This API call has no request parameters.
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
--request DELETE --header "X-Api-Key: your-api-key"
```
@ -1054,19 +1084,20 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc \
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"pause_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"pause_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
"resume_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/resume",
"ping_url": "PING_ENDPOINTf618072a-7bde-4eee-af63-71a77c5723bc",
"status": "new",
"started": false,
"tags": "prod www",
"timeout": 3600,
"update_url": "SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
"update_url": "SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
}
```
## List check's logged pings {: #list-pings .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>/pings/`
`GET SITE_ROOT/api/v2/checks/<uuid>/pings/`
Returns a list of pings this check has received.
@ -1091,7 +1122,7 @@ number of returned pings depends on the account's billing plan: 100 for free acc
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \
curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \
--header "X-Api-Key: your-api-key"
```
@ -1153,7 +1184,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \
## Get a ping's logged body {: #ping-body .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>/pings/<n>/body`
`GET SITE_ROOT/api/v2/checks/<uuid>/pings/<n>/body`
Returns a ping's logged body. The response always has the `Content-Type: text/plain`
response header, and the ping body is returned verbatim in the response body.
@ -1172,14 +1203,14 @@ response header, and the ping body is returned verbatim in the response body.
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body \
curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body \
--header "X-Api-Key: your-api-key"
```
## List check's status changes {: #list-flips .rule }
`GET SITE_ROOT/api/v1/checks/<uuid>/flips/`<br>
`GET SITE_ROOT/api/v1/checks/<unique_key>/flips/`
`GET SITE_ROOT/api/v2/checks/<uuid>/flips/`<br>
`GET SITE_ROOT/api/v2/checks/<unique_key>/flips/`
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").
@ -1191,21 +1222,21 @@ seconds=&lt;value&gt;
Example:
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?seconds=3600`
`SITE_ROOT/api/v2/checks/<uuid|unique_key>/flips/?seconds=3600`
start=&lt;value&gt;
: Returns flips that are newer than the specified UNIX timestamp.
Example:
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?start=1592214380`
`SITE_ROOT/api/v2/checks/<uuid|unique_key>/flips/?start=1592214380`
end=&lt;value&gt;
: Returns flips that are older than the specified UNIX timestamp.
Example:
`SITE_ROOT/api/v1/checks/<uuid|unique_key>/flips/?end=1592217980`
`SITE_ROOT/api/v2/checks/<uuid|unique_key>/flips/?end=1592217980`
### Response Codes
@ -1228,7 +1259,7 @@ end=&lt;value&gt;
### Example Request
```bash
curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
curl SITE_ROOT/api/v2/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
--header "X-Api-Key: your-api-key"
```
@ -1253,7 +1284,7 @@ curl SITE_ROOT/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
## List Existing Integrations {: #list-channels .rule }
`GET SITE_ROOT/api/v1/channels/`
`GET SITE_ROOT/api/v2/channels/`
Returns a list of integrations belonging to the project.
@ -1268,7 +1299,7 @@ Returns a list of integrations belonging to the project.
### Example Request
```bash
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/channels/
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v2/channels/
```
### Example Response
@ -1292,7 +1323,7 @@ curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/channels/
## List Project's Badges {: #list-badges .rule }
`GET SITE_ROOT/api/v1/badges/`
`GET SITE_ROOT/api/v2/badges/`
Returns a map of all tags in the project, with badge URLs for each tag. SITE_NAME
provides badges in a few different formats:
@ -1322,7 +1353,7 @@ of all checks in the project.
### Example Request
```bash
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/badges/
curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v2/badges/
```
### Example Response

1189
templates/docs/apiv1.html
File diff suppressed because it is too large
View File

1368
templates/docs/apiv1.md
File diff suppressed because it is too large
View File

3
templates/front/docs_single.html

@ -31,7 +31,8 @@
<li class="nav-header">API</li>
{% include "front/docs_nav_item.html" with slug="http_api" title="Pinging API" %}
{% include "front/docs_nav_item.html" with slug="api" title="Management API" %}
{% include "front/docs_nav_item.html" with slug="apiv1" title="Management API v1" %}
{% include "front/docs_nav_item.html" with slug="api" title="Management API v2" %}
<li class="nav-header">Pinging Examples</li>
{% include "front/docs_nav_item.html" with slug="reliability_tips" title="Reliability Tips" %}

Loading…
Cancel
Save