Maintenance windows in our API

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

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,
      "starts_at": "2020-01-09 10:37:24",
      "ends_at": "2020-01-09 10:42:24"
    },
    {
      "id": 102,
      "site_id": 1,
      "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,
  "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).

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.

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