Website checks in our API

We'll assume you've already got the API authentication settled and you have our API key with you (this is the Authorization header in all the examples used below).

Get all checks for a particular site #

To know what checks are available to you, you'll need to query the sites API call first. Per site, you'll be given a set of check IDs.

In this example, we'll get the details for site ID 99. Notice the checks data attribute.

$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/99 \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Here's the response:

{
  "id": 1,
  "url": "https://yoursite.tld",
  ...
  "checks": [
    {
      "id": 1,
      "type": "uptime",
      "label": "Uptime",
      "enabled": true,
      "latest_run_ended_at": "2019-09-16 07:29:02",
      "latest_run_result": "succeeded"
    },
    {
      "id": 2,
      "type": "broken_links",
      "label": "Broken links",
      "enabled": true,
      "latest_run_ended_at": "2019-09-16 07:29:05",
      "latest_run_result": "failed"
    },
    {
      "id": 3,
      "type": "mixed_content",
      "label": "Mixed content",
      "enabled": true,
      "latest_run_ended_at": "2019-09-16 07:29:05",
      "latest_run_result": "succeeded"
    },
    {
      "id": 4,
      "type": "certificate_health",
      "label": "Certificate health",
      "enabled": true,
      "latest_run_ended_at": "2019-09-16 07:29:02",
      "latest_run_result": "succeeded"
    },
    {
      "id": 5,
      "type": "certificate_transparency",
      "label": "Certificate transparency",
      "enabled": true,
      "latest_run_ended_at": "2019-09-16 07:29:02",
      "latest_run_result": "succeeded"
    }
  ],
}

Per check, you'll see its id. Once you know that ID, you can enable or disable that check or request a new run, on the spot.

Enable & disable a check #

Let's take the first check ID, 1, as an example. First, we'll enable the check.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/checks/1/enable \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

You make a POST call to /api/checks/{id}/enable to enable that check. As a result, you'll be given a confirmation payload.

{
  "id": 405,
  "type": "uptime",
  "enabled": true
}

To disable, make a similar POST to the /disable endpoint.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/checks/1/disable \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

The resulting payload will confirm the enabled attribute is set to false.

{
  "id": 405,
  "type": "uptime",
  "enabled": false
}

From that point forward, we'll no longer run that particular check.

If you want to trigger an on-demand run of a check, for instance a new mixed content or broken links scan, you can send an API call to the /request-run endpoint.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/checks/1/request-run \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

To confirm, we'll give the details of the check once again.

Snooze and unsnooze a check #

You can temporarily snooze, or silence, a particular check. We will still perform the checks, but won't send out any notifications in the period that a check is snoozed. For more details on how this option works, have a look at our snooze documentation.

If you prefer to stop monitoring a check for a particular period, it's better to disable it and enable it again later on.

To snooze a check, you can call the /api/checks/{id}/snooze endpoint and tell it how long the check should be snoozed using the minutes payload, formatted in JSON.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/checks/1/snooze \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"minutes":"10"}'

If you receive an HTTP/1.1 200 OK response, the snooze was applied correctly.

To unsnooze, or remove the silencing of alerts, you can call the /api/checks/{id}/unsnooze endpoint.

$ curl -X POST https://ohdear.app/api/checks/1/unsnooze \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If you once again received an HTTP/1.1 200 OK response, the snooze was correctly removed.

Return properties #

The response gives you some basic details of a check.

  • id: an internal identifier to Oh Dear
  • type: what type of check this is. Possible values are: uptime, performance, broken_links, certificate_health, mixed_content and certificate_transparency.
  • label: a human readable label of the check
  • enabled: a boolean value to indicate if this check is enabled or not. Possible values are: true or false.
  • latest_run_ended_at: a timestamp, in UTC, of the last time this check was run
  • latest_run_result: the status of the last run, can be succeeded, warning or failed

More properties will be added over time.

Was this page helpful to you? Feel free to reach out via support@ohdear.app or on Twitter via @OhDearApp if you have any other questions. We'd love to help!