The Oh Dear API
The Oh Dear API lets you configure everything about our application through a simple, structured Application Programming Interface (API).
Everything you see in your dashboard can be controlled with the API. And as a bonus, all changes you make with the API will be visible in realtime on your dashboard.
Getting started
Let's help get you started.
- Learn about our API authentication and generate your first API key
- Retrieve a list of all your sites and their checks with the API.
- Configure your status pages automatically.
Optionally, we provide a PHP SDK package to help get you started and a list of data types we use in our API.
API endpoints
All Oh Dear API endpoints are located at https://ohdear.app/api. From there on, you will find a logical structure that follows to the REST standard.
Here's a quick summary of the API methods.
GET: all GET requests are for data retrieval only (site listing, account info, ...) and will never modify any data.POST: a POST method will add new sites or checks to Oh DearDELETE: the DELETE method is used to delete certain sites or checks from your account.PUT: this method is used to update information on existing sites, checks or your account.
In general, GET requests can be performed as many times as you'd like (they are idempotent), all other methods actually transform data in your account and will cause changes to take effect.
Response data
All responses from the Oh Dear API will be formatted as JSON.
Here's an example payload of the /api/sites endpoint, that lists all sites.
{ "data": [ { "id": 1, "url": "https://yoursite.tld", ... }, { "id": 2, "url": "https://yourothersite.tld", ... } ] }
Each endpoint will return specific data for that request. More info on that in the sites and checks pages.
Get your API token
Once you are logged in to your dashboard navigate to API access and create your API token.
You can name your token, so you know where this one is going to be used, in case you ever need to revoke it.
Once you create a token, it'll be shown only once to you. Make sure to store it safely, after this it can only be revoked and you can generate a new token for use.
Once you have your token, you can authenticate against the application.
By default, tokens can perform any actions to everything in your Oh Dear account. You can also create API tokens that only can be used in API calls to a selection of sites and status pages.
Authenticate against the API
The token you've received can be used as the Authorization header.
Here's a curl example of how you can authenticate against the API. In this example, it'll list all sites in your account.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The token bgUKSWYL30iHg5w0WTDGHfubt5L1HBTr0atAehCeSqwNTqkU9rOmsNEmWf6Y is used to authenticate. The /api/sites endpoint is hit to retrieve all sites. The resulting response payload may look like this.
{ "data": [ { "id": 1, "url": "https://yoursite.tld", ... }, { "id": 2, "url": "https://yourothersite.tld", ... } ] }
The actual payload is usually much bigger, but that's described in more detail in the sites and checks page.
Data types
Check Types
uptimeperformancebroken_linksmixed_contentlighthousecronapplication_healthsitemapdnsdomaincertificate_health
Link Types
linkimagescriptstylesheetog:image
Check Results
pendingsucceededwarningfailederrored-or-timed-out
Summarized Check Results
succeededwarningfailed
Crawler/Sitemap Speed
slowestslowdefaultfastfastest
Lighthouse Slowdown Modifier
0(fastest) to5(slowest)
Lighthouse continent
europenorth-americaasia
Response Header Conditions
containsnot containsequalsmatches pattern
Uptime Check Locations
Africa
cape town
Asia
bangaloreseoulsingaporetokyo
Australia
sydney
Canada
toronto
Europe
frankfurtlondonparis
Middle East
bahrain
South America
sao paulo
US East
new york
US Mid
dallas
US West
los angelessan francisco
DNS Record Types
AAAAACAACNAMEMXNSSOASRVTXTPTR
Uptime check HTTP Verb
getpostpatchput
Sites
Get all sites in your account
The /api/sites endpoint lists all your sites in your account.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
As a result, you get the details for every site you've added.
{ "data": [ { "id": 1, "url": "http://yoursite.tld", "sort_url": "yoursite.tld", "label": "your-site", "team_id": 1, "group_name": null, "tags": ["tag a", "tag b"], "notes": "custom notes", "latest_run_date": "2019-09-16 07:29:02", "summarized_check_result": "succeeded", "created_at": "20171106 07:40:49", "updated_at": "20171106 07:40:49", "checks": [ { "id": 100, "type": "uptime", "label": "Uptime", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:02", "latest_run_result": "succeeded", "summary": "Up" }, { "id": 101, "type": "broken_links", "label": "Broken links", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:05", "latest_run_result": "succeeded", "summary": "" } ] }, { "id": 2, "url": "https://yourothersite.tld", "sort_url": "yourothersite.tld", "label": "my-site", "team_id": 1, "group_name": "My group", "tags": [], "notes": "", "latest_run_date": "2019-09-16 07:29:02", "summarized_check_result": "failed", "created_at": "20171108 07:40:16", "updated_at": "20171108 07:40:16", "checks": [ { "id": 1, "type": "uptime", "label": "Uptime", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:02", "latest_run_result": "succeeded", "summary": "up" }, { "id": 2, "type": "broken_links", "label": "Broken links", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:05", "latest_run_result": "failed", "summary": "1 found" }, { "id": 3, "type": "mixed_content", "label": "Mixed content", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:05", "latest_run_result": "succeeded", "Summary": "" }, { "id": 4, "type": "certificate_health", "label": "Certificate health", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:02", "latest_run_result": "failed", "Summary": "Problems detected" } ] } ] }
Let's drill this down, because the 2 sites that are listed each have different checks.
The first one is an http:// site, without TLS encryption. Since we can't monitor certificates or mixed content, we only check the uptime of the site and the broken links.
That's why there are only 2 checks item for that site.
The second site is an https:// site, and it gets all the available monitoring. More on each check in our dedicated checks page.
Get a specific site via the API
If you don't want to retrieve all sites, you can get a specific site if you know its ID. The example below will get the details of site ID 99.
$ 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'
The resulting pageload of both calls above is a single site.
{ "id": 99, "url": "http://yoursite.tld", "sort_url": "yoursite.tld", ... "checks": [ { ... }, ... ] }
Notice how this payload does not contain the data block (the API call to retrieve all sites does).
Return properties
The response gives you a lot of details per site. Here's the specifics;
id: an internal identifier to Oh Dearurl: the URL you used to submit this site to Oh Dear, including the protocol.sort_url: the url without the protocol and without thewww.prefix.friendly_name: the friendly name of a sitelabel: contains thefriendly_nameif one is specified, otherwise this contains thesort_url.team_id: every site belongs to a Team, this is its ID. A team can consist of multiple members (including yourself). Since you can belong to multiple teams, the corresponding team ID will be shown for every site. To know which team this is, have a look at the user info API call.group_name: the name of the group your site belongs totags: the names of the tags associated with your sitelatest_run_date: the date & time of the last time one of the checks in this site has run.summarized_check_result: this gives you an overview of the health of your site at a glance. Possible values aresucceeded,warningorfailed. To get the details of the status, you'll have to check the output of eachcheck.uses_https: whether it has anhttps://prefix.checks: an array of all checks that have been added to this site. More details on the checks page.broken_links_check_include_external_links: boolean, whether the crawler will check for external links or not.broken_links_whitelisted_urls: array of ignored URLs that should not be reported if they contain broken links.created_atandupdate_at: timestamp values for when it was created and when the site's properties were last updated.
More properties will be added over time.
Getting a summary of the results of a check
Oh Dear can perform various checks (uptime, mixed content, broken links, ...) for your sites.
If you want to know the status of a particular check, you can query the /api/sites/{siteId}/check-summary/{checkType} endpoint.
The checkType segment can be one of the check types we support.
Here's an example:
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/99/check-summary/uptime \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The response holds two properties:
result: this is the result of the check. Possible values arepending,succeeded,warning,failedorerrored-or-timed-out.summary: a human-readable summary of the check result
Add a site through the API
To add a site, create a POST call to the /api/sites/ endpoint. Here's an example to add the site https://mybrandnewsite.tld to Oh Dear.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"url":"https://mybrandnewsite.tld", "team_id":"1"}'
Remember that we love JSON? Your request payload should also be valid JSON. The minimum actual payload, when formatted, looks like this.
{ "url": "https://mybrandnewsite.tld", "team_id": "1" }
Mandatory fields are the url we should monitor and the team_id where this site should be added to. To find out the teams you belong to, see the user info API call.
If the API call succeeded, you'll be given output like this, showcasing every check that was added.
{ "id": 173, "url": "https://mybrandnewsite.tld", "sort_url": "mybrandnewsite.tld", "team_id": 1, ... "checks": [ { "id": 560, "type": "certificate_health", "enabled": true, "settings": [] }, { "id": 561, "type": "mixed_content", "enabled": true, "settings": [] }, ... ] }
Add a site with enabled checks
When creating a site you can control which checks get enabled. You can do so by passing an array with one of these check types.
Here's an example payload where a site is created with only the uptime and mixed_content checks enabled.
{ "url": "https://mybrandnewsite.tld", "team_id": "1", "checks": ["uptime", "mixed_content"] }
For more details on each check, have a look at the checks API endpoint.
Add a site with custom settings
If you need to control the settings of a site, you can pass additional parameters in the payload. Here's an example of a site with all possible settings. You can also control the monthly site report settings in this payload using the send_report_to_emails and include_check_types_in_report settings.
Please be aware:
urlis requiredteam_idis required and should be a team you belong tochecksis required and should be an array of check typesapplication_health_check_secretshould not be present if you want to generate a random secret- default values will be used for any settings not present in the payload
- we suggest only adding settings you want to change from the defaults
{ "url": "https://ohdear.app/docs", "team_id": 1, "checks": [ "uptime", "performance", "broken_links", "mixed_content", "lighthouse", "cron", "application_health", "sitemap", "dns", "domain", "certificate_health" ], "group_name": "Internal", "friendly_name": "Documentation", "tags": ["internal", "production", "docs"], "notes": "Internal notes for our team members", "description": "Oh Dear documentation", "uptime_check_location": "paris", "uptime_check_expected_final_redirect_url": "https://redirect-to-this-url.com", "uptime_check_failed_notification_threshold": 2, "uptime_check_http_verb": "get", "uptime_check_timeout": 5, "uptime_check_max_redirect_count": 5, "uptime_check_payload": [ { "name": "payload-name-1", "value": "payload-value-1" } ], "uptime_check_valid_status_codes": ["2*"], "uptime_check_look_for_string": null, "uptime_check_absent_string": null, "uptime_check_expected_response_headers": [ { "name": "my-response-header", "condition": "equals", "value": "my-response-value" } ], "http_client_headers": [ { "name": "my-header", "value": "my-value" } ], "performance_threshold_in_ms": 3500, "performance_change_percentage": 50, "crawler_headers": [ { "name": "my-broken-links-header", "value": "my-broken-links-value" } ], "broken_links_check_include_external_links": false, "broken_link_types": ["link", "image", "script", "stylesheet", "og:image"], "broken_links_whitelisted_urls": [], "respect_robots": true, "sitemap_path": "/sitemap.xml", "sitemap_speed": "slow", "application_health_check_result_url": "https://mybrandnewsite.tld/health", "application_health_headers": [ {"name": "my-header", "value": "my-value"} ], "certificate_health_check_expires_soon_threshold_in_days": 14, "dns_check_nameservers_in_sync": true, "dns_monitor_main_domain": false, "dns_extra_cnames": ["cname1", "cname2"], "dns_ignored_record_types": ["A", "CNAME"], "domain_check_expires_soon_threshold_in_days": 30, "lighthouse_check_continent": "europe", "lighthouse_cpu_slowdown_modifier": 0, "send_report_to_emails": [ "[email protected]", "[email protected]" ], "include_check_types_in_report": [ "uptime", "performance", "broken_links", "mixed_content", "lighthouse", "cron", "application_health", "sitemap", "dns", "domain", "certificate_health", ] }
Error handling
If an error occurred, you'll be given a non-HTTP/200 response code. The resulting payload might look like this.
{ "message": "The given data was invalid.", "errors": { "url": ["The url field is required."], "team_id": ["The team id field is required."] } }
If you've got both the url and the team_id in your payload, but the data is invalid, you'll get a detailed error message.
{ "message": "The given data was invalid.", "errors": { "url": ["You should enter a url that starts with either \"http://\" or \"https://\"."], "team_id": ["You do not belong to that team."] } }
Updating site settings
You can update the site settings by performing a PUT request to the /api/sites/{siteId} endpoint.
The payload is the same as creating a site wit the following differences:
- not all keys are required (only the ones you want to update)
urlis not required (but can be updated if needed)team_idis not allowed as a site cannot be moved between teamsapplication_health_check_secretshould not be present if you do not want to change the previously stored secret andnullwill remove the secret.
{ "url": "https://ohdear.app/docs", "checks": [ "uptime", "performance", "broken_links", "mixed_content", "lighthouse", "cron", "application_health", "sitemap", "dns", "domain", "certificate_health" ], "group_name": "Internal", "friendly_name": "Documentation", "tags": ["internal", "production", "docs"], "notes": "Internal notes for our team members", "description": "Oh Dear documentation", "uptime_check_location": "paris", "uptime_check_expected_final_redirect_url": "https://redirect-to-this-url.com", "uptime_check_failed_notification_threshold": 2, "uptime_check_http_verb": "get", "uptime_check_timeout": 5, "uptime_check_max_redirect_count": 5, "uptime_check_payload": [ { "name": "payload-name-1", "value": "payload-value-1" } ], "uptime_check_valid_status_codes": ["2*"], "uptime_check_look_for_string": null, "uptime_check_absent_string": null, "uptime_check_expected_response_headers": [ { "name": "my-response-header", "condition": "equals", "value": "my-response-value" } ], "http_client_headers": [ { "name": "my-header", "value": "my-value" } ], "performance_threshold_in_ms": 3500, "performance_change_percentage": 50, "crawler_headers": [ { "name": "my-broken-links-header", "value": "my-broken-links-value" } ], "broken_links_check_include_external_links": false, "broken_link_types": ["link", "image", "script", "stylesheet", "og:image"], "broken_links_whitelisted_urls": [], "respect_robots": true, "sitemap_path": "/sitemap.xml", "sitemap_speed": "slow", "application_health_check_result_url": "https://mybrandnewsite.tld/health", "application_health_check_secret": null, "application_health_headers": [ {"name": "my-header", "value": "my-value"} ], "certificate_health_check_expires_soon_threshold_in_days": 14, "dns_check_nameservers_in_sync": true, "dns_monitor_main_domain": false, "dns_extra_cnames": ["cname1", "cname2"], "dns_ignored_record_types": ["A", "CNAME"], "domain_check_expires_soon_threshold_in_days": 30, "lighthouse_check_continent": "europe", "lighthouse_cpu_slowdown_modifier": 0, "send_report_to_emails": [ "[email protected]", "[email protected]" ], "include_check_types_in_report": [ "uptime", "performance", "broken_links", "mixed_content", "lighthouse", "cron", "application_health", "sitemap", "dns", "domain", "certificate_health" ] }
Deleting a site
Use the DELETE method to delete a site through the API. In this example, we'll delete the site with ID 1.
$ OHDEAR_TOKEN="your API token"
$ curl -X DELETE https://ohdear.app/api/sites/1 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Notice how we're calling the DELETE method on the /api/sites/1 endpoint. The 1 in the URL determines which site to delete.
Ignoring broken links URLs
You can add a single URL to our crawler ignore list with an easy API method. This is primarily used to quickly add just a single URL, for instance in an overview-screen where you allow users to whitelist URLs.
If you want to ignore several URLs, or remove ignored URLs, please see the more extended update-broken-links-settings API call.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/add-to-broken-links-whitelist \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"whitelistUrl": "https://externalsite.tld/page1"
}'
Modifying site settings
We now support updating all site settings from a single endpoint. But we still support updating some settings on the following dedicated endpoints.
Broken links settings
You can control whether our crawler should check for external links or stick to internal pages only.
Additionally, you can update the site settings and ignore URLs that are known to be broken (or out of your control), so we no longer report if we find broken pages listed on them.
Note: this lists the source URLs, not the destinations.
$ OHDEAR_TOKEN="your API token"
$ curl -X PUT https://ohdear.app/api/sites/1/update-broken-links-settings \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"broken_links_check_include_external_links": true,
"broken_links_whitelisted_urls_string":"
https://externalsite.tld/page1
https://externalsite.tld/page2"
}'
The inputs are as follows:
broken_links_check_include_external_links: boolean value, eithertrueorfalsebroken_links_whitelisted_urls_string: string value, new-line separated list of fully qualified URLs that we should ignore and not report on
Both can be used independently, if you just want to update the broken_links_check_include_external_links setting, there is no need to also submit the list of ignored URLs.
Updating HTTP client request headers
When performing the uptime, mixed content and broken links checks, Oh Dear can add extra headers to each request we make to a site.
You can update used headers by performing this PUT request:
$ OHDEAR_TOKEN="your API token"
$ curl -X PUT https://ohdear.app/api/sites/1/update-http-client-headers \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
{"name": "my-header", "value": "value-of-header"}
]'
Updating the uptime check payload
Oh Dear can send form data along with the uptime check for all non-GET requests.
You can update the sent payload by performing this PUT request:
$ OHDEAR_TOKEN="your API token"
$ curl -X PUT https://ohdear.app/api/sites/1/update-uptime-check-payload \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
{"name": "my-name", "value": "my-value"}
]'
Checks
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", "settings": [] }, { "id": 2, "type": "broken_links", "label": "Broken links", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:05", "latest_run_result": "failed", "settings": [] }, { "id": 3, "type": "mixed_content", "label": "Mixed content", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:05", "latest_run_result": "succeeded", "settings": [] }, { "id": 4, "type": "certificate_health", "label": "Certificate health", "enabled": true, "latest_run_ended_at": "2019-09-16 07:29:02", "latest_run_result": "succeeded", "settings": [] } ] }
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.
Snooze and unsnooze a scheduled task
In addition to snoozing the entire check, you can also snooze individual scheduled tasks.
To snooze a specific scheduled task, you can call the /api/sites/{site_id}/cron-checks/{task_id}/snooze endpoint and tell it how long the check should be snoozed using the minutes payload, formatted in JSON.
Call /api/sites/{site_id}/cron-checks/{task_id}/unsnooze to remove any active snooze for this task.
Tip: You can find the cron_id by calling the /api/sites/{site_id}/cron-checks endpoint or by looking at the cron check details in the Oh Dear application.
Snooze and unsnooze an application health check
You can also snooze and unsnooze an individual application health check.
To snooze an application health check, you can call the /api/sites/{site_id}/application-health-checks/{health_check_id}/snooze endpoint and tell it how long the check should be snoozed using the minutes payload, formatted in JSON.
Call /api/sites/{site_id}/application-health-checks/{health_check_id}/unsnooze to remove any active snooze for this check.
Tip: You can find the application health check id by calling the /api/sites/{site_id}/application-health-checks endpoint or by looking at the application health check details in the Oh Dear application.
Return properties
The response gives you some basic details of a check.
id: an internal identifier to Oh Deartype: what type of check this is. Possible values are:uptime,performance,broken_links,certificate_health,mixed_content,cron,dnsandapplication_health.label: a human readable label of the checkenabled: a boolean value to indicate if this check is enabled or not. Possible values are:trueorfalse.latest_run_ended_at: a timestamp, in UTC, of the last time this check was runlatest_run_result: the status of the last run, can bepending,succeeded,warningorfailedsummary: a human readable summary of the check resultactive_snooze: an object containing the details of the active snooze for this check, ornullif no snooze is active
More properties will be added over time.
Active snooze
The active_snooze property is an object containing the details of the active snooze for this check, or null if no snooze is active.
"active_snooze": { "id": 1, "starts_at": "2025-04-30 11:35:20", "ends_at": "2025-04-30 11:40:20", "snoozed_by": "Sean White", "unsnoozed_by": null, "source": "API", "created_at": "2025-04-30 11:35:20" }
Uptime
If a site has the uptime check enabled, you can query the uptime percentages via the /api/uptime endpoint. To use this endpoint you'll need to now the site id of your site. You can get all sites ids by calling the get all sites endpoint.
To retrieve you'll need to specify a period via the started_at and ended_at filters. The period may not be longer than 2 years. The split value determines how fine grained the answer periods should be. Valid values are hour, day and month.
In this example we are going to get the uptime for site id 1.
$ OHDEAR_TOKEN="your API token"
$ curl "https://ohdear.app/api/sites/1/uptime?filter[started_at]=20180101000000&filter[ended_at]=20180101235959&split=day" \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Here's what the output could look like:
[ {"datetime":"2018-01-01 00:00:00","uptime_percentage":100}, {"datetime":"2018-01-01 01:00:00","uptime_percentage":99.76}, {"datetime":"2018-01-01 02:00:00","uptime_percentage":100}, {"datetime":"2018-01-01 03:00:00","uptime_percentage":98.34}, ... {"datetime":"2018-01-01 23:00:00","uptime_percentage":100} ]
Downtime
You can query the downtime via the /api/sites/{siteId}/downtime endpoint. To use this endpoint you'll need to now the site id of your site. You can get all sites ids by calling the get all sites endpoint.
To retrieve you'll need to specify a period via the started_at and ended_at filters.
In this example we are going to get the downtime periods for site number 1.
$ OHDEAR_TOKEN="your API token"
$ curl "https://ohdear.app/api/sites/1/downtime?filter[started_at]=20180101150000&filter[ended_at]=20180101160000" \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Here's what the output could look like:
{ "data": [ { "id": 1, "started_at": "2018-01-01 15:00:00", "ended_at": "2018-01-01 15:07:00", "notes_html": "We contacted our provider and they fixed the issue.", "notes_markdown": "We contacted our provider and they fixed the issue." } ] }
Deleting a downtime period
You can delete a downtime period by calling the /api/downtime/{downtimeId} endpoint. Make sure to use the DELETE http verb. To use this endpoint you'll need to now the downtime id, which you can get to by calling the get downtime endpoint.
Performance records
Retrieving performance records
You can retrieve all performance records by calling the /performance-records endpoint. This can be done per website in your Oh Dear account, so you'll need to know your site's ID first.
A filter is necessary: you decide from when to when the data should be returned.
In this example we'll get a list of all sites and use the site ID to retrieve the performance data.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
{
"data": [
{
"id": 1,
"url": "https://www.yoursite.tld",
"...",
}
]
}
Here, we'll query the performance data between yesterday and today, on the 1m timeframe. That's our most granular & most detailed timeframe available.
$ curl https://ohdear.app/api/sites/1/performance-records?filter[start]=20240419132501&filter[end]=20240420132501&filter[group_by]=minute \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
{
"data": [
{
"dns_time_in_seconds": 0.001399,
"tcp_time_in_seconds": 0.01651,
"ssl_handshake_time_in_seconds": 0.053852,
"remote_server_processing_time_in_seconds": 0.021595,
"download_time_in_seconds": 0.000535,
"total_time_in_seconds": 0.09389099999999999,
"curl": {
"namelookup_time": 0.001399,
"connect_time": 0.017909,
"appconnect_time": 0.071761,
"starttransfer_time": 0.093356,
"pretransfer_time": 0.071864,
"redirect_time": 0,
"total_time": 0.093891,
"header_size": 1261,
"size_download": 12814,
"speed_download": 137784
},
"created_at": "2021-08-10 18:57:00"
{
...
}
],
}
If there are no performance records in the requested period, you'll receive an empty data array.
{ "data": [] }
Selecting the granularity for data
In the example above, we grouped the performance records per minute. These records are stored for roughly 14 days. We also stored performance records per hour (which are kept for a couple of weeks) and per day (which are kept eternally).
You can request the hourly and daily records by passing hour or day to group_by.
Sorting the results
By default, the records will be sorted by newest records first. In other words, the most recent performance data will always be on top.
You can change the sorting by adding an explicit sort=created_at query parameter to the API call. You can negate the sort (ie: reverse it) by making it sort=-created_at.
$ curl https://ohdear.app/api/sites/1/performance-records?filter[start]=20240419132501&filter[end]=20240420132501&filter[group_by]=minute&sort=created_at \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The only field you can use to sort data is the created_at column.
Performance record data explained
The API returns the detailed performance metrics for each datapoint we have.
{ "dns_time_in_seconds": 0.001399, "tcp_time_in_seconds": 0.01651, "ssl_handshake_time_in_seconds": 0.053852, "remote_server_processing_time_in_seconds": 0.021595, "download_time_in_seconds": 0.000535, "total_time_in_seconds": 0.09389099999999999, "curl": { "namelookup_time": 0.001399, "connect_time": 0.017909, "appconnect_time": 0.071761, "starttransfer_time": 0.093356, "pretransfer_time": 0.071864, "redirect_time": 0, "total_time": 0.093891, "header_size": 1261, "size_download": 12814, "speed_download": 137784 }, "created_at": "2021-08-10 18:57:00" },
In the curl key, you find the raw performance values that curl produces when we called your site. In most cases, it will be expressed in milliseconds, not seconds. So 0.0429 can be read as 42.9ms. By multiplying each value by 1,000, you get the value in milliseconds.
The data represents the following part of the request:
time_namelookup: The time it takes to resolve the domain name to an IP address via DNS.time_connect: The time it takes to connect to the remote host (TCP three-way handshake).time_appconnect: The total time it took for the TLS handshake to complete (cipher negotiation & encryption).time_remoteserver: The time it took the server to process the request and start sending the first byte of the page.time_download: The time, in seconds, it took for the page to be downloaded.time_total: The total time it took from start to finish of this request.
Broken Links
Retrieving broken links
If a site has the broken links check enabled, you can get all detected broken links via the /api/broken-links endpoint. To use this endpoint you'll need to now the site id of your site. You can get all sites ids by calling the get all sites endpoint.
In this example we are going to get the broken-links for site number 1.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/broken-links/1 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Here's what the output could look like:
{ "data": [ { "crawled_url": "https://example.com/broken", "relative_crawled_url": "/broken", "status_code": 404, "found_on_url": "https://example.com", "relative_found_on_url": "https://example.com", "internal": true } ] }
Mixed content
Retrieving mixed content
If a site has the mixed content check enabled, you can get all detected mixed content via the /api/mixed-content endpoint. To use this endpoint you'll need to now the site id of your site. You can get all sites ids by calling the get all sites endpoint.
In this example we are going to get the broken-links for site number 1.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/mixed-content/1 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Here's what the output could look like:
{ "data": [ { "element_name": "img", "mixed_content_url": "http://example.com/image.jpg", "found_on_url": "https://example.com" } ] }
Certificate Health
Retrieving info on the certificate health
If a site has the certificate health check enabled, you can get feedback on the result via the /api/certificate-health endpoint. To use this endpoint you'll need to now the site id of your site. You can get all sites ids by calling the get all sites endpoint.
Here's an example where we get the certificate health of the site with ID 1.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/certificate-health/1 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The output will be an object with these 3 keys:
certificate_details: an array with some details on the detected certificatecertificate_checks: an array with info on the checks we performed on the certificatecertificate_chain_issuers: an array containing the names of all the issuers in the complete certificate chain
Here's what it looks like.
{ "certificate_details": { "issuer": "Let's Encrypt Authority X3", "valid_from": "2019-09-10 15:16:01", "valid_until": "2019-12-09 15:16:01" }, "certificate_checks": [ { "type": "notFound", "label": "Certificate present", "passed": true }, { "type": "expiresSoon", "label": "Will not expire in the next 14 days", "passed": true }, { "type": "coversWrongDomain", "label": "Covers the right domain", "passed": true }, { "type": "doesNotConnectWithRootCertificate", "label": "Connects with a root certificate", "passed": true }, { "type": "notYetActive", "label": "Is currently active", "passed": true }, { "type": "isSelfSigned", "label": "Is not self signed", "passed": true }, { "type": "usesInvalidHash", "label": "Uses valid hash", "passed": true }, { "type": "hasExpired", "label": "Has not expired", "passed": true }, { "type": "hasChanged", "label": "Unchanged since last checked", "passed": true } ], "certificate_chain_issuers": [ "US, Let's Encrypt, Let's Encrypt Authority X3", "Digital Signature Trust Co., DST Root CA X3" ] }
To determine the overal health of the certificate, you can look at all the checks in the certificate_checks result.
Those with a value of "passed": false have a failed check.
Retrieving detected certificates
This endpoint allows you to view all certificates that have been detected for a specific site, including historical certificates.
Here's an example where we get all detected certificates for the site with ID 1.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/detected-certificates \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The response will contain a paginated list of detected certificates:
{ "data": [ { "id": 123, "site_id": 1, "fingerprint": "abcd1234567890abcd1234567890abcd12345678", "certificate_details": { "issuer": "Let's Encrypt Authority X3", "domain": "example.com", "additional_domains": [ "www.example.com" ], "valid_from": "2023-10-01T12:00:00Z", "valid_until": "2024-01-01T12:00:00Z", "days_until_expiration": 45, "signature_algorithm": "sha256WithRSAEncryption", "is_valid": true, "is_expired": false }, "created_at": "2023-10-01T12:30:00Z", "updated_at": "2023-10-01T12:30:00Z" } ], "links": { "first": "https://ohdear.app/api/sites/1/detected-certificates?page=1", "last": "https://ohdear.app/api/sites/1/detected-certificates?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 15, "to": 1, "total": 1 } }
You can also retrieve a specific detected certificate by its ID:
$ curl https://ohdear.app/api/sites/1/detected-certificates/123 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Filtering and sorting
You can filter detected certificates by fingerprint:
$ curl https://ohdear.app/api/sites/1/detected-certificates?filter[fingerprint]=abcd1234567890abcd1234567890abcd12345678 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
You can sort the results by created_at, updated_at, or fingerprint:
$ curl https://ohdear.app/api/sites/1/detected-certificates?sort=-created_at \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Use a minus sign (-) before the field name to sort in descending order.
User Info
Retrieve your team & user info
Make a GET request to the /api/me endpoint.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/me \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
If the API call succeeded, you'll be presented with your team & user info.
Return properties
Here's an example payload of the API call.
{ "id": 1, "name": "Firstname Lastname", "email": "[email protected]", "photo_url": "https://www.gravatar.com/avatar/...jpg", "teams": [ { "id": 1, "name": "Your Team Name" } ] }
Let's look at all the properties that are returned.
id: the identifier of the user this API key belongs to.name,emailandphoto_url: personal information about your account.teams: an array of teams this user belongs to. A user can be a member of several teams.
The teams property has an id (team ID) and a human readable name. The team id will be used throughout all API calls to determine what team you want to add sites to.
Status Pages
You can make a GET HTTP call to the /api/status-pages endpoint to retrieve all your configured status pages.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/status-pages \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
As a result, you'll get a list of all your status pages and their metadata.
{ "data": [ { "id": 1, "team": { "id": 1, "name": "Your Team Name" }, "title": "Your Status Page Title", "domain": "status.your-domain.tld", "slug": "autem-quos-accusantium-esse-ex-numquam-odio", "full_url": "https://ohdear.app/status-page/autem-quos-accusantium-esse-ex-numquam-odio", "timezone": "Europe/Brussels", "summarized_status": "up", "sites": [ { "id": 1, "url": "https://site1.tld", ... }, { "id": 7, "url": "https://site2.tld", ... } ], "created_at": "2019-09-13 07:06:51", "updated_at": "2019-09-13 07:06:51" } ], "links": { "first": "https://ohdear.app/api/status-pages?page%5Bnumber%5D=1", "last": "https://ohdear.app/api/status-pages?page%5Bnumber%5D=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "https://ohdear.app/api/status-pages", "per_page": 200, "to": 2, "total": 2 } }
There's a lot of data in there, let's unpack it.
The following fields are available in the output:
data: this is an array that contains a list of all your status pages.team: because you can belong to multiple teams, we'll clarify which team this status page belongs to.summarized_status: this can either beup,downorunknown. It'sdownwhen at least one of the sites in the status page has an uptime check that reported it as down.sites: this is an array with all sites that are added to this status page. It will also contain all checks from each website, so you have all information easily available to you.- the
linksandmetaoutput are for pagination when you have many status pages.
Retrieve a single status page
You can also pass the ID of a status page to the /api/status-pages/{id} endpoint to get the details of a specific status page.
In this example, we'll retrieve the status page with ID 1.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/status-pages/1 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The resulting output will contain the details of that specific status page. Note that it does not have the data container that is used when retrieving all sites through the API.
{ "id": 1, "team": { "id": 1, "name": "Your Team Name" }, "title": "Your Status Page Title", ... "updates": [ { "id": 65, "title": "Your status page update title", ... }, ... ], "sites": [ { "id": 1, "url": "https://site1.tld", }, ... ] }
In addition to the similar output of the /api/status-pages endpoint described above, when you get the data from a single status page we'll also include its updates.
This will contain an array of all status page updates & messages that have been posted to your status page.
For more details, have a look at our status page updates API documentation.
The rest of the data is similar to the output described above.
Create a status page
You can create a status page by making a POST HTTP call to the /api/status-pages endpoint. The following fields are required:
team_id: the ID of the team you want to create the status page fortitle: the title of your status pagesites: an array of sites you want to add to the status pageid: the ID of the site you want to add to the status pageclickable: boolean whether the site should be clickable on the status page
{ "team_id": 1, "title": "My New Status Page", "sites": [ { "id": 1, "clickable": true }, { "id": 2, "clickable": false } ] }
Delete a status page
If you make a DELETE HTTP call to the /api/status-pages/ID, you can delete a status page through the API.
In this example we are going to delete the status page with ID 99.
$ OHDEAR_TOKEN="your API token"
$ curl -i -X DELETE https://ohdear.app/api/status-pages/99 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Add sites to a status page
You can add a site to an existing status page by making a POST HTTP call to the /api/status-pages/{statusPage}/sites endpoint. The following fields are accepted:
sync: (optional) boolean whether existing sites should be removed and replaced with the given sitessites: an array of sites you want to add to the status pageid: the ID of the site you want to add to the status pageclickable: boolean whether the site should be clickable on the status page
{ "sync": true, "sites": [ { "id": 17, "clickable": true } ] }
The sync field is optional. If it's set to true, the existing sites will be removed and replaced with the given sites. If it's set to false, the given sites will be appended to the status page.
Remove a site from a status page
You can also remove a site from a status page by making a DELETE HTTP call to the /api/status-pages/{statusPage}/sites/{site} endpoint.
$ OHDEAR_TOKEN="your API token"
$ curl -i -X DELETE https://ohdear.app/api/status-pages/1/sites/17 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
A HTTP/1.1 204 No Content response indicates that the site was successfully removed from the status page.
HTTP/1.1 204 No Content X-RateLimit-Limit: 180 X-RateLimit-Remaining: 176 ...
Each status page can contain updates or messages. These are used to communicate to your customers or clients in times of downtime or maintenance.
You can post these messages from your dashboard or with our API.
To list the updates or messages from a single status page, you'll need to know its ID. You can retrieve that using the /api/status-pages API call explained in the status pages API documentation.
Once you have your ID, you can get the details as follows:
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/status-pages/1/updates \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The resulting output will contain an array of all the updates to that specific status page.
If there are no status messages, the array will be empty.
{ "data": [] }
If there are messages, we'll return those in the data field.
{ "data": [ { "id": 65, "title": "3rd party API issue resolved", "text": "We have contacted our API provider and they have resolved the situation, everything is back to normal. We apologize for the inconvenience!", "pinned": false, "severity": "resolved", "time": "2019-09-16 08:24:00", "status_page_url": "https://ohdear.app/status-page/your-slug" }, { "id": 64, "title": "We are experiencing an outage on our service", "text": "Due to errors in our 3rd party API provider, we are experiencing an outage of our website. Our team is working on getting it resolved ASAP.", "pinned": false, "severity": "high", "time": "2019-09-16 08:11:00", "status_page_url": "https://ohdear.app/status-page/your-slug" } ] }
These are sorted by newest message to oldest. The output contains the following fields:
id: the ID of that particular updatetitleandtext: these are shown on your status pagepinned: when set totrue, this update will be posted at the very top of your status page. There can only be 1 pinned message.severity: these can beinfo,warning,high,resolvedorscheduled. You are free to use these any way you like. Theresolvedupdates will be posted in green on your status page to inform the user the problem has been resolved.time: the date in UTC at which this status page was posted. This will get translated to your configured timezone.
Post a new update to your status page
To add a new update or message to your status page, you can make a POST call to the /api/status-page-updates endpoint.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/status-page-updates \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"status_page_id":1, "title":"Our site is down", "text":"We are working on it!", "severity":"high", "time":"2019-09-16 10:24","pinned":true}'
As a confirmation, we'll return an HTTP/1.1 201 Created with the received data fields.
{ "id": 66, "title": "Our site is down", "text": "We are working on it!", "pinned": true, "severity": "high", "time": "2019-09-16 08:24:00", "status_page_url": "https://ohdear.app/status-page/your-slug" }
The POST API call should contain a valid json body with the following fields.
status_page_id: the ID of the status page where you want to add this update.title: the titel of your status updatetext: a longer text describing what is happening or how you're resolving the problemseverityare:info,warning,high,resolvedorscheduled.time: a date field that acts as a timestamp for this update, should be in UTC in theY-m-d H:iformat.pinned: whether this status page message should be pinned to the very top of the page. There can only be 1 pinned message, when set totrueit will remove thepinnedattribute from any other message.status_page_url: the public URL of your status page. If you have configured a custom domain, this will point to your custom domain - otherwise it'll be the URL with your status page slug on the ohdear.app domain.
Delete an update on your status page
Let's use the API to delete the status message we just posted above, the one with ID 66.
$ OHDEAR_TOKEN="your API token"
$ curl -X DELETE https://ohdear.app/api/status-page-updates/66 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
If the response code is HTTP/1.1 204 No Content, the deletion of the status update was successful.
Maintenance windows
Retrieving maintenance periods
You can list all maintenance windows by calling the /maintenance-periods endpoint. This can be done per website in your Oh Dear account, so you'll need to know your site's ID first.
In this example we'll get a list of all sites and use the site ID to retrieve the maintenance periods.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
{
"data": [
{
"id": 1,
"url": "https://www.yoursite.tld",
"...",
}
]
}
$ curl https://ohdear.app/api/sites/1/maintenance-periods \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
{
"data": [
{
"id": 101,
"site_id": 1,
"name": "Deployment"
"starts_at": "2020-01-09 10:37:24",
"ends_at": "2020-01-09 10:42:24"
},
{
"id": 102,
"site_id": 1,
"name": ""
"starts_at": "2020-01-09 10:37:32",
"ends_at": "2020-01-09 10:42:32"
},
}
If there are no maintenance periods, you'll receive an empty data array.
{ "data": [] }
If there are maintenance windows, we'll show the time of each start end end period.
{ "data": [ { "starts_at": "2020-01-09 14:00:00", "ends_at": "2020-01-10 14:00:00" } ] }
These dates are all shown in the timezone of your team. If your timezone is configured as America/Vancouver, you'll see the dates & times shown in your own local timezone.
Creating a new maintenance period on-demand
This method applies on a per-site basis. If you want to put the site with ID 1 in maintenance right now, you can call this API method.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/start-maintenance \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
{
"id": 101,
"site_id": 1,
"name": "Optional name of your maintenance period"
"starts_at": "2020-01-09 10:28:54",
"ends_at": "2020-01-09 11:28:54"
}
This will start a maintenance period that, by default, will last for 60 minutes. In the response, you'll find the confirmation of the start- and end-date.
To stop the maintenance period, call the /stop-maintenance endpoint.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/stop-maintenance \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
This will change the end-date of the currently active maintenance period to the time you've called the API.
This way, you still have a list of maintenance periods to look back on (as an audit list).
On-demand maintenance window with limited duration
If you prefer, you can also pass along the amount of seconds a maintenance period needs to be active in the /start-maintenance API call. This can be lowered or increased depending on your needs and provides a safe fallback in case your scripts execute the start-maintenance API call, but never get to the stop-maintenance call.
To do so, add a stop_maintenance_after_seconds POST value in JSON, as shown here.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/start-maintenance \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"stop_maintenance_after_seconds":"300"}'
{
"id": 101,
"site_id": 1,
"starts_at": "2020-01-09 10:37:32",
"ends_at": "2020-01-09 10:42:32"
}
This will create a maintenance period for 300 seconds, or 5 minutes, as confirmed by the JSON output.
Creating a maintenance period with custom start and end times
If you don't use the on-demand maintenance windows as shown above, you can create maintenance windows with a custom start- and end-date. This allows you to schedule maintenance ahead of times.
Since maintenance windows are applicable per website, you need the site ID of the website you want to put in maintenance.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/maintenance-periods \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"site_id":"1", "starts_at":"2020-02-01 14:00","ends_at":"2020-02-01 18:00"}'
{
"id": 101,
"site_id": "1",
"starts_at": "2020-02-01 14:00:00",
"ends_at": "2020-02-01 18:00:00"
}
The API expects the dates to be formatted as Y:m:d H:i (no seconds) and the ends_at needs to be further in the future than the starts_at.
All dates should be in your local timezone, as configured in your team settings. (You don't need to convert anything to UTC, write the dates as they feel natural to you.)
Deleting a maintenance period
To delete a maintenance period, you need its ID. That can be retrieved with the /maintenance-periods API call, as shown above.
$ OHDEAR_TOKEN="your API token"
$ curl -X DELETE https://ohdear.app/api/maintenance-periods/101 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The example above deletes the maintenance period with ID 101.
Cron Job Monitoring
Get all cron jobs for a website
Cron job monitors are attached to a website in Oh Dear. To retrieve a list of monitored cron jobs, you'll the website ID first.
The /api/sites/{$siteId}/cron-checks endpoint lists all your cron job monitors for that particular site.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/cron-checks \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
As a result, you get the details for every cron job monitor attached to this site, together with its latest status:
{ "data": [ { "id": 1, "uuid": "0d210b09", "name": "cronjob number one", "type": "simple", "description": "a description goes here", "frequency_in_minutes": 15, "grace_time_in_minutes": 5, "cron_expression": null, "server_timezone": "Europe/Brussels", "ping_url": "https://ping.ohdear.app/0d210b09", "created_at": "2020-07-28 13:27:02", "latest_result": "pingFinished", "latest_ping_at": "2020-11-16 09:19:40", "human_readable_latest_ping_at": "5 minutes ago" }, { "id": 2, "uuid": "8eb64808", "name": "cronjob number two", "type": "simple", "description": "a description goes here", "frequency_in_minutes": 60, "grace_time_in_minutes": 10, "cron_expression": null, "server_timezone": "Europe/Brussels", "ping_url": "https://ping.ohdear.app/8eb64808", "created_at": "2020-07-28 13:27:02", "latest_result": "pingFinished", "latest_ping_at": "2020-11-16 09:19:40", "human_readable_latest_ping_at": "5 minutes ago" } ] }
The response is a JSON encoded array with all the details of the cron jobs you defined to be monitored.
Result types
The latest_result response in the API can be one of the following values.
These are values actively submitted by your application to your cron monitoring URL endpoint:
pingStarting: we have received the "started" pingback from your applicationpingFinished: we have received the "finished" pingback from your application, indicating no errors occurredpingFailed: we have received the "failed" pingback from your application, indicating errors have occured
These are values we may have detected ourselves, without active participation from your application:
checkRanTooLate: because we did not receive a new ping URL on time, we have marked the cron task as failed because it ran too latesentCronNotExutedOnTimeNotification: because the check didn't execute on time, we have sent the "did not run on time" notificationsentPingFailedNotification: your application reported us that the last ping contained a failure, we have now sent a notification that the ping failed
The success states of a cronjob are determined only by the pingFinished result. All other types indicate that we are either waiting on a ping, have received a failed ping, or have received no ping at all.
Create a simple cron job monitor
You can create a new cron job monitor using our API. You'll need the site ID where you want to attach the new monitor to.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/cron-checks \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"name": "your cron job name",
"type": "simple",
"frequency_in_minutes": 10,
"grace_time_in_minutes": 15,
"description": "a description goes here"
}'
The example above will create a new cron job monitor by providing both the frequency and the gracetime. Note how the type is set to simple.
The response will include the Ping URL you can point your cron jobs to:
{ "id": 12, "uuid": "ba4322cf", "name": "your cron job name", "type": "simple", "description": "a description goes here", "frequency_in_minutes": 10, "grace_time_in_minutes": 15, "cron_expression": "", "server_timezone": null, "ping_url": "https://ping.ohdear.app/ba4322cf", "created_at": "2020-08-03 12:18:33" }
The ping_url should be used in your scripts to report back the status of your cron jobs to us.
Create a new cron job monitor via crontab expression
Alternatively, you can create a new cron job monitor using the crontab expression as well.
Note how in this example the type is set to cron instead of simple.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/cron-checks \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"name": "your cron job name",
"type": "cron",
"cron_expression":"* * * * *",
"grace_time_in_minutes": 10,
"description": "a description goes here",
"server_timezone": "UTC"
}'
The example above will create a new cron job monitor using the crontab expression * * * * * to indicate it should run every minute.
The response will include the Ping URL you can point your cron jobs to:
{ "id": 10, "uuid": "19eea41a", "name": "your cron job name", "type": "cron", "description": "a description goes here", "frequency_in_minutes": 0, "grace_time_in_minutes": 10, "cron_expression": "* * * * *", "server_timezone": "UTC", "ping_url": "https://ping.ohdear.app/19eea41a", "created_at": "2020-08-03 12:13:53" }
The ping_url should be used in your scripts to report back the status of your cron jobs to us.
Bulk cron job synchronization
For our PHP-SDK, we've created a mass-update endpoint you can use to update all cron jobs for a single site. This will remove any cron job not explicitly in this sync API call, so it is a destructive action.
$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/cron-checks/sync \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"cron_checks": [
{
"name": "cron job #1",
"type": "cron",
"cron_expression":"* * * * *",
"grace_time_in_minutes": 10,
"description": "description for cron #1",
"server_timezone": "UTC"
},
{
"name": "cron job #2",
"type": "cron",
"cron_expression":"* * * * *",
"grace_time_in_minutes": 10,
"description": "description for cron #2",
"server_timezone": "UTC"
}
]
}'
The return data, if the API call was successful, is a confirmation of each cron job definition together with all its metadata.
[ { "id": 9, "uuid": "c1803dce", "name": "cron job #1", "type": "cron", "description": "description for cron #1", "frequency_in_minutes": null, "grace_time_in_minutes": 10, "cron_expression": "* * * * *", "server_timezone": "UTC", "ping_url": "https://ping.ohdear.app/c1803dce", "created_at": "2020-09-03 19:20:25", "latest_result": "pingFinished", "latest_ping_at": "2020-11-16 09:19:40" }, { "id": 10, "uuid": "40e8e39e", "name": "cron job #2", "type": "cron", "description": "description for cron #2", "frequency_in_minutes": null, "grace_time_in_minutes": 10, "cron_expression": "* * * * *", "server_timezone": "UTC", "ping_url": "https://ping.ohdear.app/40e8e39e", "created_at": "2020-09-03 19:20:25", "latest_result": "pingFinished", "latest_ping_at": "2020-11-16 09:19:40" } ]
Error handling
If an error occured, you'll be given a non-HTTP/200 response code. The resulting payload might look like this.
{ "message": "The given data was invalid.", "errors": { "name": ["There already exist a cron check with this name for this site."] } }
DNS Records
Retrieving DNS history for a site
To retrieve a list of your entire Dns history and issues, you'll the website ID first.
The /api/sites/{$siteId}/dns-history-items endpoint lists all DNS related information we retrieved for your domain.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/dns-history-items \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
As a result, you get the history of the DNS records for your domain, together with all issues we found. Here's an example result for records retrieved for a https://freek.dev.
The results are sorted in reverse chronological order: the topmost item will contain your current DNS records.
{ "data": [ { "id": 2, "authoritative_nameservers": [ "ns1.openprovider.nl", "ns2.openprovider.be", "ns3.openprovider.eu" ], "dns_records": [ { "host": "freek.dev", "ttl": 1017, "class": "IN", "type": "A", "ip": "138.197.187.74" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 10, "target": "aspmx.l.google.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 20, "target": "alt1.aspmx.l.google.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 20, "target": "alt2.aspmx.l.google.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 30, "target": "aspmx2.googlemail.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 30, "target": "aspmx3.googlemail.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "NS", "target": "ns1.openprovider.nl" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "NS", "target": "ns2.openprovider.be" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "NS", "target": "ns3.openprovider.eu" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "SOA", "mname": "ns1.openprovider.nl", "rname": "dns.openprovider.eu", "serial": 2021080201, "refresh": 10800, "retry": 3600, "expire": 604800, "minimum_ttl": 3600 }, { "host": "freek.dev", "ttl": 1060, "class": "IN", "type": "TXT", "txt": "v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all" } ], "raw_dns_records": { "ns1.openprovider.nl": [ "freek.dev.\t\t1017\tIN\tA\t138.197.187.74", "freek.dev.\t\t1060\tIN\tTXT\t\"v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all\"", "freek.dev.\t\t4435\tIN\tMX\t10\taspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt1.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt2.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx2.googlemail.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx3.googlemail.com.", "freek.dev.\t\t4435\tIN\tNS\tns1.openprovider.nl.", "freek.dev.\t\t4435\tIN\tNS\tns2.openprovider.be.", "freek.dev.\t\t4435\tIN\tNS\tns3.openprovider.eu.", "freek.dev.\t\t4435\tIN\tSOA\tns1.openprovider.nl.\tdns.openprovider.eu.\t2021080201\t10800\t3600\t604800\t3600" ], "ns2.openprovider.be": [ "freek.dev.\t\t1060\tIN\tTXT\t\"v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all\"", "freek.dev.\t\t4435\tIN\tMX\t10\taspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt1.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt2.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx2.googlemail.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx3.googlemail.com.", "freek.dev.\t\t4435\tIN\tNS\tns1.openprovider.nl.", "freek.dev.\t\t4435\tIN\tNS\tns2.openprovider.be.", "freek.dev.\t\t4435\tIN\tNS\tns3.openprovider.eu.", "freek.dev.\t\t4435\tIN\tSOA\tns1.openprovider.nl.\tdns.openprovider.eu.\t2021080201\t10800\t3600\t604800\t3600" ], "ns3.openprovider.eu": [ "freek.dev.\t\t1017\tIN\tA\t138.197.187.74", "freek.dev.\t\t1060\tIN\tTXT\t\"v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all\"", "freek.dev.\t\t4435\tIN\tMX\t10\taspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt1.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt2.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx2.googlemail.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx3.googlemail.com.", "freek.dev.\t\t4435\tIN\tNS\tns1.openprovider.nl.", "freek.dev.\t\t4435\tIN\tNS\tns2.openprovider.be.", "freek.dev.\t\t4435\tIN\tNS\tns3.openprovider.eu.", "freek.dev.\t\t4435\tIN\tSOA\tns1.openprovider.nl.\tdns.openprovider.eu.\t2021080201\t10800\t3600\t604800\t3600" ] }, "issues": [ { "name": "NameserversAreNotInSync", "nameservers": [ "ns2.openprovider.be" ] } ], "diff_summary": "No changes", "created_at": "2021-11-05 16:07:38" }, { "id": 1, "authoritative_nameservers": [ "ns1.openprovider.nl", "ns2.openprovider.be", "ns3.openprovider.eu" ], "dns_records": [ { "host": "freek.dev", "ttl": 1017, "class": "IN", "type": "A", "ip": "138.197.187.74" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 10, "target": "aspmx.l.google.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 20, "target": "alt1.aspmx.l.google.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 20, "target": "alt2.aspmx.l.google.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 30, "target": "aspmx2.googlemail.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "MX", "pri": 30, "target": "aspmx3.googlemail.com" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "NS", "target": "ns1.openprovider.nl" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "NS", "target": "ns2.openprovider.be" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "NS", "target": "ns3.openprovider.eu" }, { "host": "freek.dev", "ttl": 4435, "class": "IN", "type": "SOA", "mname": "ns1.openprovider.nl", "rname": "dns.openprovider.eu", "serial": 2021080201, "refresh": 10800, "retry": 3600, "expire": 604800, "minimum_ttl": 3600 }, { "host": "freek.dev", "ttl": 1060, "class": "IN", "type": "TXT", "txt": "v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all" } ], "raw_dns_records": { "ns1.openprovider.nl": [ "freek.dev.\t\t1017\tIN\tA\t138.197.187.74", "freek.dev.\t\t1060\tIN\tTXT\t\"v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all\"", "freek.dev.\t\t4435\tIN\tMX\t10\taspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt1.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt2.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx2.googlemail.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx3.googlemail.com.", "freek.dev.\t\t4435\tIN\tNS\tns1.openprovider.nl.", "freek.dev.\t\t4435\tIN\tNS\tns2.openprovider.be.", "freek.dev.\t\t4435\tIN\tNS\tns3.openprovider.eu.", "freek.dev.\t\t4435\tIN\tSOA\tns1.openprovider.nl.\tdns.openprovider.eu.\t2021080201\t10800\t3600\t604800\t3600" ], "ns2.openprovider.be": [ "freek.dev.\t\t1017\tIN\tA\t138.197.187.74", "freek.dev.\t\t1060\tIN\tTXT\t\"v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all\"", "freek.dev.\t\t4435\tIN\tMX\t10\taspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt1.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt2.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx2.googlemail.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx3.googlemail.com.", "freek.dev.\t\t4435\tIN\tNS\tns1.openprovider.nl.", "freek.dev.\t\t4435\tIN\tNS\tns2.openprovider.be.", "freek.dev.\t\t4435\tIN\tNS\tns3.openprovider.eu.", "freek.dev.\t\t4435\tIN\tSOA\tns1.openprovider.nl.\tdns.openprovider.eu.\t2021080201\t10800\t3600\t604800\t3600" ], "ns3.openprovider.eu": [ "freek.dev.\t\t1017\tIN\tA\t138.197.187.74", "freek.dev.\t\t1060\tIN\tTXT\t\"v=spf1 include:amazonses.com include:eu.mailgun.org include:spf.factuursturen.be include:sendgrid.net include:_spf.google.com a mx ~all\"", "freek.dev.\t\t4435\tIN\tMX\t10\taspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt1.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t20\talt2.aspmx.l.google.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx2.googlemail.com.", "freek.dev.\t\t4435\tIN\tMX\t30\taspmx3.googlemail.com.", "freek.dev.\t\t4435\tIN\tNS\tns1.openprovider.nl.", "freek.dev.\t\t4435\tIN\tNS\tns2.openprovider.be.", "freek.dev.\t\t4435\tIN\tNS\tns3.openprovider.eu.", "freek.dev.\t\t4435\tIN\tSOA\tns1.openprovider.nl.\tdns.openprovider.eu.\t2021080201\t10800\t3600\t604800\t3600" ] }, "issues": [], "diff_summary": "No changes", "created_at": "2021-11-05 16:02:38" } }
Possible values of issues
The issues property will return an array with issues we detected. Each item in that array will have a property name that can contain on of the following values:
CouldNotDiscoverNameservers: we couldn't find the authoritative nameservers for your domainCouldNotFindAnyDnsRecords: some nameservers of your domain did not return any records. These nameservers are listed in thenameserversproperty of this arrayNameserversAreNotInSync: a nameserver of your domain returned different records than the other nameservers. The names of the nameservers that are not in sync are listed in thenameserversproperty of this array
Application Health Monitoring
Retrieving application health check for a site
To retrieve a list of application health checks, you'll need the website ID first.
The /api/sites/{$siteId}/application-health-checks endpoint lists all application health checks that are running for
your site.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/application-health-checks \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
This is what could get as a result:
{ "data": [ { "id": 1, "name": "DiskUsage", "label": "Disk usage", "status": "failed", "message": "The disk is nearly full (91%)", "short_summary": "91%", "meta": { "usage": 91 }, "detected_at": "2021-01-01 00:00:00", "updated_at": "2021-01-01 00:00:00" } ] }
Available fields
The message property will be filled when a check failed. It will contain the message that we also have sent via a
notification.
The short_summary property contains a string that we'll also display on the application health check overview of your
site.
The status property can contain one of the following values:
ok: the check was okwarning: the check is closed to failingfailed: the check did failcrashed: something went wrong running the check itselfskipped: the check wasn't performed in this run
The meta property contains an object that contain extra info that was sent along with the check result.
Retrieving the history of a health check
The /api/sites/{$siteId}/application-health-checks/{$applicationHealthCheckId} endpoint lists the history of results
of an application health check.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/application-health-checks/1 \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
It will return the history of the check results. The newest items appear first in the list.
{ "data": [ { "id": 2, "status": "ok", "message": "", "short_summary": "60%", "meta": { "usage": 60 }, "detected_at": "2021-01-01 00:01:00", "updated_at": "2021-01-01 00:01:00" }, { "id": 1, "status": "failed", "message": "The disk is nearly full (91%)", "short_summary": "91%", "meta": { "usage": 91 }, "detected_at": "2021-01-01 00:00:00", "updated_at": "2021-01-01 00:00:00" } ] }
Domain monitoring
Retrieving domain information for a site
To retrieve domain information of a site, you'll need the website ID first.
The /api/sites/{$siteId}/domain endpoint displays domain related information we retrieved for your domain.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/domain \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
The response contains the most important dates of the domain, and the domain status. In the rdap_domain_response key, you'll find the raw response we got from RDAP about your domain. The created_at key contains the date on which we queried RDAP.
Here's example output when monitoring google.com:
{ "expires_at": "2028-09-14 04:00:00", "registered_at": "1997-09-15 04:00:00", "last_changed_at": "2019-09-09 15:39:04", "last_updated_in_rdap_db_at": "2022-06-11 00:32:59", "domain_statuses": { "client delete prohibited": true, "client transfer prohibited": true, "client update prohibited": true, "server delete prohibited": true, "server transfer prohibited": true, "server update prohibited": true }, "rdap_domain_response": { "links": [ { "rel": "self", "href": "https://rdap.verisign.com/com/v1/domain/GOOGLE.COM", "type": "application/rdap+json", "value": "https://rdap.verisign.com/com/v1/domain/GOOGLE.COM" }, { "rel": "related", "href": "https://rdap.markmonitor.com/rdap/domain/GOOGLE.COM", "type": "application/rdap+json", "value": "https://rdap.markmonitor.com/rdap/domain/GOOGLE.COM" } ], "events": [ { "eventDate": "1997-09-15T04:00:00Z", "eventAction": "registration" }, { "eventDate": "2028-09-14T04:00:00Z", "eventAction": "expiration" }, { "eventDate": "2019-09-09T15:39:04Z", "eventAction": "last changed" }, { "eventDate": "2022-06-11T00:32:59Z", "eventAction": "last update of RDAP database" } ], "handle": "2138514_DOMAIN_COM-VRSN", "status": [ "client delete prohibited", "client transfer prohibited", "client update prohibited", "server delete prohibited", "server transfer prohibited", "server update prohibited" ], "ldhName": "GOOGLE.COM", "notices": [ { "links": [ { "href": "https://www.verisign.com/domain-names/registration-data-access-protocol/terms-service/index.xhtml", "type": "text/html" } ], "title": "Terms of Use", "description": ["Service subject to Terms of Use."] }, { "links": [ { "href": "https://icann.org/epp", "type": "text/html" } ], "title": "Status Codes", "description": [ "For more information on domain status codes, please visit https://icann.org/epp" ] }, { "links": [ { "href": "https://icann.org/wicf", "type": "text/html" } ], "title": "RDDS Inaccuracy Complaint Form", "description": [ "URL of the ICANN RDDS Inaccuracy Complaint Form: https://icann.org/wicf" ] } ], "entities": [ { "roles": ["registrar"], "handle": "292", "entities": [ { "roles": ["abuse"], "vcardArray": [ "vcard", [ ["version", [], "text", "4.0"], ["fn", [], "text", ""], [ "tel", { "type": "voice" }, "uri", "tel:+1.2086851750" ], ["email", [], "text", "[email protected]"] ] ], "objectClassName": "entity" } ], "publicIds": [ { "type": "IANA Registrar ID", "identifier": "292" } ], "vcardArray": [ "vcard", [ ["version", [], "text", "4.0"], ["fn", [], "text", "MarkMonitor Inc."] ] ], "objectClassName": "entity" } ], "secureDNS": { "delegationSigned": false }, "nameservers": [ { "ldhName": "NS1.GOOGLE.COM", "objectClassName": "nameserver" }, { "ldhName": "NS2.GOOGLE.COM", "objectClassName": "nameserver" }, { "ldhName": "NS3.GOOGLE.COM", "objectClassName": "nameserver" }, { "ldhName": "NS4.GOOGLE.COM", "objectClassName": "nameserver" } ], "objectClassName": "domain", "rdapConformance": [ "rdap_level_0", "icann_rdap_technical_implementation_guide_0", "icann_rdap_response_profile_0" ] }, "created_at": "2022-06-10 20:33:06" }
Lighthouse SEO monitoring
To retrieve Lighthouse SEO reports of a site, you'll need the website ID first.
Getting the latest report
The /api/sites/{$siteId}/lighthouse-reports/latest endpoint displays that latest Lighthouse report we generated for your site.
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/lighthouse-reports/latest \
-H "Authorization: Bearer $OHDEAR_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
This will return a result like
{ "id": 1, "performance_score": 50, "accessibility_score": 98, "best_practices_score": 92, "seo_score": 92, "progressive_web_app_score": 30, "first_contentful_paint_in_ms": 1851.45, "speed_index_in_ms": 1866, "largest_contentful_paint_in_ms": 1851.45, "time_to_interactive_in_ms": 2473.87, "total_blocking_time_in_ms": 123.77, "cumulative_layout_shift": 0.01, "performed_on_checker_server": "lighthouse-checker-frankfurt-1", "json_report": { /* Omitted for brevity, will contain the full JSON report generated by the lighthouse tool */ }, "issues": [ { "category": "performance", "actualScore": 50, "notificationThreshold": 70 } ], "created_at": "2023-01-14 00:00:55" }
Getting a list of all reports
The /api/sites/{$siteId}/lighthouse-reports endpoint returns all Lighthouse SEO reports.
Here's some example output. Notice that we don't return the json_report in the response for this endpoint.
{ "data": [ { "id": 1423, "performance_score": 97, "accessibility_score": 98, "best_practices_score": 92, "seo_score": 92, "progressive_web_app_score": 30, "first_contentful_paint_in_ms": 1851.45, "speed_index_in_ms": 1866, "largest_contentful_paint_in_ms": 1851.45, "time_to_interactive_in_ms": 2473.87, "total_blocking_time_in_ms": 123.77, "cumulative_layout_shift": 0.01, "performed_on_checker_server": "lighthouse-checker-frankfurt-1", "issues": [ { "category": "performance", "actualScore": 97, "notificationThreshold": 99 } ], "created_at": "2023-01-14 00:00:55" }, { "id": 1321, "performance_score": 89, "accessibility_score": 98, "best_practices_score": 92, "seo_score": 92, "progressive_web_app_score": 30, "first_contentful_paint_in_ms": 294.65, "speed_index_in_ms": 328, "largest_contentful_paint_in_ms": 294.65, "time_to_interactive_in_ms": 1585.48, "total_blocking_time_in_ms": 445.9, "cumulative_layout_shift": 0.06, "performed_on_checker_server": "lighthouse-checker-frankfurt-1", "issues": [ { "category": "performance", "actualScore": 89, "notificationThreshold": 99 } ], "created_at": "2023-01-12 23:38:19" } ], "links": { "first": "https://ohdear.app/api/sites/1/lighthouse-reports?page%5Bnumber%5D=1", "last": "https://ohdear.app/api/sites/1/lighthouse-reports?page%5Bnumber%5D=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://ohdear.app/api/sites/1/lighthouse-reports?page%5Bnumber%5D=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://ohdear.app/api/sites/1/lighthouse-reports", "per_page": 200, "to": 2, "total": 2 } }
Getting a specific Lighthouse SEO report
The /api/sites/{$siteId}/lighthouse-reports/{$reportId} endpoint returns a specific report. You can get the $reportId by retrieving the list of Lighthouse reports (see above)
Here's an example response.
{ "id": 1, "performance_score": 50, "accessibility_score": 98, "best_practices_score": 92, "seo_score": 92, "progressive_web_app_score": 30, "first_contentful_paint_in_ms": 1851.45, "speed_index_in_ms": 1866, "largest_contentful_paint_in_ms": 1851.45, "time_to_interactive_in_ms": 2473.87, "total_blocking_time_in_ms": 123.77, "cumulative_layout_shift": 0.01, "performed_on_checker_server": "lighthouse-checker-frankfurt-1", "json_report": { /* Omitted for brevity, will contain the full JSON report generated by the lighthouse tool */ }, "issues": [ { "category": "performance", "actualScore": 50, "notificationThreshold": 70 } ], "created_at": "2023-01-14 00:00:55" }
Notification destinations
Using our API, you can retrieve notification destination of your site or teams. Because the results of these API calls can contain sensitive values, only admins and team owners are allowed to use them.
Getting the notification destinations of all your teams
The /api/team-notification-destinations endpoint will return all notification destinations defined on the team level
for all your teams.
{ "data": [ { "id": 123, "team_id": 1, "channel": "mail", "destination": { "mail": "[email protected]" }, "notification_types": [ "UptimeCheckFailedNotification", "UptimeCheckRecoveredNotification", ... ] } ] }
Getting the notification destinations of a site
To retrieve the notification destinations of a site, you'll need the website ID first.
The /api/sites/{$siteId}/notification-destinations endpoint will return all notification destinations for the site.
{ "data": [ { "id": 456, "channel": "mail", "destination": { "mail": "[email protected]" }, "notification_types": [ "UptimeCheckFailedNotification", "UptimeCheckRecoveredNotification", ... ] } ] }
Getting the notification destinations of a tag
The /api/tags/notification-destinations endpoint will return all notification destinations defined on the tag level
for all your teams.
{ "data": [ { "id": 123, "tag": { "id": 1, "name": "Production", "slug": "production" }, "team_id": 1, "channel": "mail", "destination": { "mail": "[email protected]" }, "notification_types": [ "UptimeCheckFailedNotification", "UptimeCheckRecoveredNotification", ... ] } ] }
Creating notification destinations
You can create a new notification destination for a site or team. The required payload is in the same format as the API to retrieve notification destinations which makes it easy to copy notification configurations across sites and teams.
Sites: /api/sites/{$siteId}/notification-destinations
Teams: /api/team-notification-destinations/{$teamId}
Tags: /api/tags/notification-destinations/{$tagId}
Payload
{ "channel": "mail", "destination": { "mail": "[email protected]" }, "notification_types": [ "UptimeCheckRecoveredNotification", "UptimeCheckFailedNotification", ] }
Note: an empty array will create your configuration but will not respond to any Oh Dear events. Make sure the array has at least one item.
Payload (all events)
You can accept all supported notification types by removing the notification_types array from your request.
{ "channel": "mail", "destination": { "mail": "[email protected]" } }
Sending a test notification
You can also trigger a test notification as part of the creation process by adding test: true|false to you request body. By default this will be false.
{ "test": true, "channel": "mail", "destination": { "mail": "[email protected]" } }
Updating notification destinations
You can update an existing notification destination by sending a PUT/PATCH request with the updated payload to the following endpoints:
Sites: /api/sites/{$siteId}/notification-destinations/{$destinationId}
Teams: /api/team-notification-destinations/{$teamId}/destination/{$destinationId}
Tags: /api/tags/notification-destinations/{$tagId}/destination/{$destinationId}
{ "test": true, "channel": "mail", "destination": { "mail": "[email protected]" } }
You can also send test notifications on updates by adding test: true to your request body. By default this will be false.
Deleting notifications destinations#
You can delete a notification destination by sending a DELETE request to the following endpoints:
Sites: /api/sites/{$siteId}/notification-destinations/{$destinationId}
Teams: /api/team-notification-destinations/{$teamId}/destination/{$destinationId}
Tags: /api/tags/{$tagId}/notification-destinations/destination/{$destinationId}
No other parameters are required and a 204 response will be returned if the deletion was successful.
Channels and destinations
Each channel requires a valid destination object. You can find the supported channels and their config objects below.
{ "channel": "mail", "destination": { "mail": "[email protected]" }, }
Discord
{ "channel": "discord", "destination": { "url": "https://discord.com/api/webhooks/your-webhook-url" } }
Microsoft Teams
{ "channel": "microsoftTeams", "destination": { "url": "https://teams.microsoft.com/webhook/your-webhook-url" } }
Pushover
{ "channel": "pushover", "destination": { "userKey": "your-user-key", "apiToken": "your-api-token", "priority": "0" } }
Priority [lowest - emergency]: -2, -1, 0, 1, 2
Slack
{ "channel": "slack", "destination": { "url": "https://hooks.slack.com/services/your-webhook-url" } }
Slack API
{ "channel": "slackApi", "destination": { "token": "xoxp-rest-of-your-token-here", "channel": "#general" } }
Telegram
{ "channel": "telegram", "destination": { "chat_id": "your-chat-id", } }
SMS
{ "channel": "sms", "destination": { "apiKey": "your-vonage-api-key", "apiSecret": "your-vonage-api-secret", "from": "your-sender-number", "to": "your-recipient-number" } }
Webhook
{ "channel": "webhooks", "destination": { "url": "https://your-webhook-url" } }
Opsgenie
{ "channel": "opsgenie", "destination": { "apiKey": "your-api-key", "euEndpoint": true, "priority": "P3" } }
Priority: P1, P2, P3, P4, P5
Pager Duty
{ "channel": "pagerDuty", "destination": { "apiKey": "your-service-key", "serviceId": "your-service-id", "fromEmail": "[email protected]" } }
Notification types
The following notification types are valid for both teams and sites:
- ApplicationHealthClientErrorNotification
- ApplicationHealthProblemDetectedNotification
- ApplicationHealthProblemFixedNotification
- ApplicationHealthResultsTooOldNotification
- BrokenLinksFoundNotification
- BrokenLinksFixedNotification
- CertificateExpiresSoonNotification
- CertificateFixedNotification
- CertificateHasChangedNotification
- CertificateUnhealthyNotification
- CronFailedNotification
- CronNotExecutedOnTimeNotification
- DnsIssuesFoundNotification
- DnsIssuesFixedNotification
- DnsRecordsChangedNotification
- DomainIssuesFoundNotification
- DomainIssuesFixedNotification
- LighthouseIssuesDetectedNotification
- LighthouseIssuesFixedNotification
- MixedContentFoundNotification
- MixedContentFixedNotification
- PerformanceDeltaExceededNotification
- PerformanceThresholdExceededNotification
- PerformanceThresholdRecoveredNotification
- SitemapIssuesFoundNotification
- SitemapIssuesFixedNotification
- UptimeCheckFailedNotification
- UptimeCheckRecoveredNotification
Team notification types
In addition to the generic notification types listed above the following are also valid for teams only:
- SiteAddedNotification
Feel free to reach out via [email protected] or on Twitter via @OhDearApp if you have any other questions. We'd love to help!
