Documentation API

  1. The REST API ⇣ allows you to fetch your metrics and automate your checks administration. It's a simple HTTPS API returning JSON.
  2. The Push API (webhooks) ⇣ allows you to receive updates in real time when your checks goes up or down.
  3. The DNS API ⇣ allows you to easy automate some networking tasks (IP filtering for example).

1. REST API

Authentication

All API calls requires authentication with an API key which can be passed either as an URL query parameter ?api-key= or as an HTTP header X-API-KEY: Sign in to see your API key.

We also offer read-only API key so you can build public integrations (like a truly custom status page or TV dashboard) directly in javascript without giving away your read/write access. If you make this API key publicly accessible, for example through javascript, be careful! All your checks will be visible including the URL parameters and custom HTTP headers which might leak sensitive information. This API key will only work with GET endpoints (green).

Compression

All API calls supports gzip compression and we recommend enabling it to increase response speed and save bandwidth. This can be achieve by passing the standard Accept-Encoding: gzip HTTP header or by using the native option provided by your HTTP client. For example with curl you can add the --compressed option (which automatically adds the header and decompress the response). This usually gives 4-6 times smaller payloads and even on a very good fiber connection, a 20-50% faster response time.

Client libraries

Here are some existing client libraries/tools to work with the API:

API calls

Accepted time formats

For the REST API parameters which accepts a time value, you have several accepted options including but not limited to:

If you have another good looking time format you can try it out and see if it works. If you ommit the timezone it'll default to UTC. Please make sure these strings are properly URL encoded before sending them or you may get wrong results (ex %2B instead of +)

2. Push API (webhooks)

Setup

To setup a new webhook, all you have to do it go the your settings page and add the desired endpoint to the list of webhook URLs. Alternatively, you can use the REST API above to manage webhooks (/api/recipients endpoint). You can add many endpoints, they'll all receive the same events. updown.io will send a POST request to all these endpoints every time an event occurs. Even though you'll often receive only one at a time, events will always be sent in an array, as we may send you multiple events in the same request in the future.

Your endpoint is supposed to respond with a HTTP 200 OK status (the body doesn't matter). Any other response will be considered an error and the webhook request will be retried up to 25 times across several days. You'll receive email warnings when your endpoint has been failing consistently for the last 10, 100 and 900 requests. After 1000 failed deliveries, the webhook endpoint will be automatically removed from your account.

Keep in mind that other events might be added at any time and you will start receiving them, so make sure your code accepts and ignores unknown events to be forward compatible.

All events include a description attribute with a plain-text summary of the event, can be useful to easily implement notification forwarding proxies.

Once you have at least one endpoint configured, you can use this page to send a test webhook.

Events

3. DNS API

We maintain some DNS records allowing you to easily automate some tasks like whitelisting our IPs in your firewall (supported by PFSense for example).

Entries