Log In
Oh Dear
Docs/API

Maintenance Windows

Maintenance windows let you suppress notifications during planned downtime. You can start maintenance immediately, schedule it for later, or set up recurring windows for regular deployment slots.

You'll need a monitor ID for most of these endpoints. All timestamps are in your team's timezone -- both when you send them and when we return them.

Example request:

$ OHDEAR_TOKEN="your API token"
$ curl "https://ohdear.app/api/monitors/1/maintenance-periods?filter[started_at]=20240101000000&filter[ended_at]=20241231235959" \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

All endpoints below follow the same authentication pattern.

Maintenance periods #

Maintenance period response fields #

Each maintenance period includes the following fields:

{
  "id": 45,
  "monitor_id": 1,
  "name": "Deployment",
  "starts_at": "2026-02-12 14:30:00",
  "ends_at": "2026-02-12 15:00:00"
}
  • id: unique identifier
  • monitor_id: the monitor this maintenance period belongs to
  • name: optional label, or null
  • starts_at: start time in your team's timezone
  • ends_at: end time in your team's timezone

Starting maintenance immediately #

POST /api/monitors/{monitorId}/start-maintenance

Starts maintenance for a monitor right now. We'll suppress notifications until the window ends.

Request body (JSON):

  • stop_maintenance_after_seconds (integer, optional) -- how long the window lasts in seconds. Minimum 5, default 3600
  • name (string, optional) -- a label for this maintenance window

Returns the maintenance period object.

Stopping active maintenance #

POST /api/monitors/{monitorId}/stop-maintenance

Ends active maintenance for a monitor. Notifications resume immediately, or after a delay if you specify one.

Request body (JSON):

  • delay_seconds (integer, optional) -- seconds to wait before resuming notifications. Minimum 1

Returns 204 No Content on success.

Creating a scheduled maintenance period #

POST /api/maintenance-periods

Schedule a future maintenance window. We'll suppress notifications during the specified period.

Request body (JSON):

  • monitor_id (integer, required) -- the monitor to schedule maintenance for
  • starts_at (string, required) -- start time in Y-m-d H:i format, in your team's timezone
  • ends_at (string, required) -- end time in Y-m-d H:i format, must be after starts_at
  • name (string, optional) -- a label for this maintenance window

Returns the maintenance period object.

Updating a scheduled maintenance period #

PUT /api/maintenance-periods/{maintenancePeriodId}

Update the times or name of a scheduled maintenance period that hasn't started yet.

Request body (JSON):

  • starts_at (string, required) -- start time in Y-m-d H:i format, in your team's timezone
  • ends_at (string, required) -- end time in Y-m-d H:i format, must be after starts_at
  • name (string, optional) -- a label for this maintenance window

Returns the updated maintenance period object.

Deleting a maintenance period #

DELETE /api/maintenance-periods/{maintenancePeriodId}

Returns 204 No Content on success.

Retrieving maintenance periods #

GET /api/monitors/{monitorId}/maintenance-periods

Returns a paginated list of maintenance periods for a monitor. Each item follows the same maintenance period shape above.

Query parameters:

  • filter[started_at] (string, optional) -- timestamp in YmdHis format
  • filter[ended_at] (string, optional) -- timestamp in YmdHis format

Recurring maintenance periods #

Recurring maintenance periods automate regular maintenance windows -- perfect for weekly deployment slots or nightly processing windows.

Recurring maintenance period response fields #

Each recurring maintenance period includes the following fields:

{
  "id": 1,
  "monitor_id": 1,
  "name": "Weekly deployment window",
  "recurrence_type": "weekly",
  "days_of_week": [2, 4],
  "day_of_month": null,
  "start_time": "02:00",
  "end_time": "03:00",
  "human_readable_schedule": "Every Tuesday and Thursday from 02:00 to 03:00",
  "last_generated_until": "2026-02-19",
  "created_at": "2026-01-15T10:00:00+00:00",
  "updated_at": "2026-01-15T10:00:00+00:00"
}
  • id: unique identifier
  • monitor_id: the monitor this recurring period belongs to
  • name: label for this recurring window, or null
  • recurrence_type: schedule type -- Possible values: daily, weekly, monthly
  • days_of_week: for weekly: array of day numbers 0-6 where 0 is Sunday, or null
  • day_of_month: for monthly: day 1-31, or null
  • start_time: HH:MM format, in your team's timezone
  • end_time: HH:MM format, in your team's timezone. If before start_time, the window spans overnight
  • human_readable_schedule: human-friendly description of the schedule
  • last_generated_until: the date (Y-m-d) up to which periods have been generated, or null
  • created_at: ISO 8601 timestamp
  • updated_at: ISO 8601 timestamp

Get a recurring maintenance period #

GET /api/recurring-maintenance-periods/{recurringMaintenancePeriodId}

Returns a single recurring maintenance period by its ID. The response follows the recurring maintenance period shape above.

List recurring maintenance periods #

GET /api/monitors/{monitorId}/recurring-maintenance-periods

Returns all recurring maintenance periods for a monitor. Each item follows the same recurring maintenance period shape above.

Create a recurring maintenance period #

POST /api/recurring-maintenance-periods

Set up a recurring maintenance window that automatically generates maintenance periods on a daily, weekly, or monthly schedule.

Request body (JSON):

  • monitor_id (integer, required) -- the monitor to create the recurring window for
  • name (string, required) -- a label for this recurring window
  • recurrence_type (string, required) -- daily, weekly, or monthly
  • start_time (string, required) -- start time in HH:MM format, in your team's timezone
  • end_time (string, required) -- end time in HH:MM format, must differ from start_time
  • days_of_week (array of integers, required for weekly) -- values 0-6 where 0 is Sunday
  • day_of_month (integer, required for monthly) -- values 1-31
  • generate_now (boolean, optional) -- immediately generates maintenance periods for the next 7 days. Default true

Returns the recurring maintenance period object.

Update a recurring maintenance period #

PUT /api/recurring-maintenance-periods/{recurringMaintenancePeriodId}

All fields are optional -- only include what you want to change.

Request body (JSON):

  • name (string, optional)
  • recurrence_type (string, optional) -- daily, weekly, or monthly
  • start_time (string, optional) -- HH:MM format, in your team's timezone
  • end_time (string, optional) -- HH:MM format
  • days_of_week (array of integers, optional)
  • day_of_month (integer, optional)
  • regenerate_future_periods (boolean, optional) -- deletes and regenerates future periods with the new schedule. Default true

Returns the updated recurring maintenance period object.

Delete a recurring maintenance period #

DELETE /api/recurring-maintenance-periods/{recurringMaintenancePeriodId}

Returns 204 No Content on success.

Query parameter:

  • delete_future_periods (boolean, optional) -- also removes future periods generated from this recurring definition. Past periods are always preserved
Was this page helpful?

Feel free to reach out via support@ohdear.app or on X via @OhDearApp if you have any other questions. We'd love to help!

Status pages
Tags and tag groups