On this page

Maintenance Windows

Schedule and manage maintenance windows. Suppress alerts during planned downtime.

Last updated · Sergio Xalambrí

Maintenance windows allow you to schedule planned downtime for your monitors. During a maintenance window, alerts can be suppressed and the status page can display a maintenance notice.

Scope

monitorType and monitorId are the window's scope, and together they mean one of three things:

  • Neither — every monitor the team has, of every kind.

  • monitorType alone — every monitor of that kind, including ones created later.

  • monitorType and monitorId — that one monitor, looked up in that kind's monitors.

A monitorId sent on its own is read as an HTTP monitor, which is what it has always meant, so clients written before the other monitor kinds arrived keep working untouched.

A monitorId that does not belong to the team, or that belongs to a different kind of monitor than monitorType names, answers a 404 not-found problem with "Monitor not found" — the window is never quietly widened to the whole team instead.

GET /api/v1/maintenance

Returns the maintenance windows for your team. This endpoint is paginated; see Pagination for how to page through the full list.

Required scope: maintenance:read

Query Parameters

  • perPageinteger

    Results per page, 1-200 (default: 50)

  • cursorstring

    Page to fetch, taken from a Link header

The cursors for this page arrive in meta.pagination:

  • meta.pagination.nextstring | null

    Cursor for the following page, null on the last

  • meta.pagination.prevstring | null

    Cursor for the preceding page, null on the first

  • meta.pagination.perPageinteger

    Results this page was built with

  • meta.pagination.totalinteger

    Maintenance windows matching, across every page

Errors (3)
StatusTypeMeaning
400bad-requestThe request is malformed
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • maintenanceWindowsMaintenanceWindow[]Required
      Show nested fields
      • idstringRequired
      • teamIdstringRequired
      • monitorTypestring | nullRequired

        Monitor type the window covers; null covers every type One of http, dns, tcp, cron, flow.

      • monitorIdstring | nullRequired

        The one monitor the window covers; null covers the whole type

      • namestringRequired
      • startsAtintegerRequired

        Epoch milliseconds

      • endsAtintegerRequired

        Epoch milliseconds

      • endedEarlyAtinteger | nullRequired

        When the window was ended early; null while it runs its course

      • suppressAlertsbooleanRequired
      • showOnStatusPagebooleanRequired
      • createdAtintegerRequired

        Epoch milliseconds

      • updatedAtintegerRequired

        Epoch milliseconds

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

    • paginationobjectRequired
      Show nested fields
      • nextstring | nullRequired

        Cursor of the following page

      • prevstring | nullRequired

        Cursor of the preceding page

      • perPageintegerRequired
      • totalinteger

cURL

Terminal
curl "https://uptime.sergiodxa.com/api/v1/maintenance?perPage=25" \
  -H "Authorization: Bearer uptime_your_api_key"
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/maintenance?perPage=25", {
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
	},
});
let result = await response.json();

Response

json
{
	"data": {
		"maintenanceWindows": [
			{
				"id": "mnt_abc123",
				"teamId": "team_xyz789",
				"monitorType": "http",
				"monitorId": "mon_def456",
				"name": "Database Migration",
				"startsAt": 1771120800000,
				"endsAt": 1771128000000,
				"endedEarlyAt": null,
				"suppressAlerts": true,
				"showOnStatusPage": true,
				"createdAt": 1771070400000,
				"updatedAt": 1771070400000
			}
		]
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z",
		"pagination": {
			"next": "eyJkIjoiYWZ0ZXIi",
			"prev": null,
			"perPage": 25,
			"total": 31
		}
	}
}

POST /api/v1/maintenance

Creates a new maintenance window and answers 201 Created.

Required scope: maintenance:write

Request Body

  • namestringRequired

    Name of the maintenance window (at least 1 character)

  • startsAtstringRequired

    Start time in ISO 8601 format

  • endsAtstringRequired

    End time in ISO 8601 format (must be after startsAt)

  • monitorTypestring

    Limit the window to one kind of monitor: http, dns, tcp, cron or flow. Sent on its own, the window covers every monitor of that kind, including ones created later.

  • monitorIdstring | null

    Limit the window to a single monitor, or null for all monitors. Sent together with monitorType, the id is looked up in that kind's monitors; sent on its own it is read as an HTTP monitor, which is what it has always meant.

  • suppressAlertsboolean

    Whether to suppress alerts during maintenance (default: true)

  • showOnStatusPageboolean

    Whether to show maintenance on status page (default: true)

Errors (7)
StatusTypeMeaning
400validation-errorThe request failed validation
400idempotency-key-invalidThe Idempotency-Key header is not valid
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
404not-foundThe resource does not exist
409idempotency-key-in-useA request with this idempotency key is still being processed
422idempotency-key-reusedThis idempotency key was already used for a different request
Response fields (201)
  • dataobjectRequired
    Show nested fields
    • maintenanceWindowobjectRequired
      Show nested fields
      • idstringRequired
      • teamIdstringRequired
      • monitorTypestring | nullRequired

        Monitor type the window covers; null covers every type One of http, dns, tcp, cron, flow.

      • monitorIdstring | nullRequired

        The one monitor the window covers; null covers the whole type

      • namestringRequired
      • startsAtintegerRequired

        Epoch milliseconds

      • endsAtintegerRequired

        Epoch milliseconds

      • endedEarlyAtinteger | nullRequired

        When the window was ended early; null while it runs its course

      • suppressAlertsbooleanRequired
      • showOnStatusPagebooleanRequired
      • createdAtintegerRequired

        Epoch milliseconds

      • updatedAtintegerRequired

        Epoch milliseconds

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl -X POST https://uptime.sergiodxa.com/api/v1/maintenance \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Migration",
    "startsAt": "2026-02-15T02:00:00Z",
    "endsAt": "2026-02-15T04:00:00Z",
    "monitorType": "http",
    "monitorId": "mon_def456",
    "suppressAlerts": true,
    "showOnStatusPage": true
  }'
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/maintenance", {
	method: "POST",
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		"name": "Database Migration",
		"startsAt": "2026-02-15T02:00:00Z",
		"endsAt": "2026-02-15T04:00:00Z",
		"monitorType": "http",
		"monitorId": "mon_def456",
		"suppressAlerts": true,
		"showOnStatusPage": true
	}),
});
let result = await response.json();

Response

json
{
	"data": {
		"maintenanceWindow": {
			"id": "mnt_abc123",
			"teamId": "team_xyz789",
			"monitorType": "http",
			"monitorId": "mon_def456",
			"name": "Database Migration",
			"startsAt": 1771120800000,
			"endsAt": 1771128000000,
			"endedEarlyAt": null,
			"suppressAlerts": true,
			"showOnStatusPage": true,
			"createdAt": 1771063200000,
			"updatedAt": 1771063200000
		}
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z"
	}
}

GET /api/v1/maintenance/:id

Returns a single maintenance window by ID.

Required scope: maintenance:read

Errors (4)
StatusTypeMeaning
400validation-errorThe request failed validation
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
404not-foundThe resource does not exist
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • maintenanceWindowobjectRequired
      Show nested fields
      • idstringRequired
      • teamIdstringRequired
      • monitorTypestring | nullRequired

        Monitor type the window covers; null covers every type One of http, dns, tcp, cron, flow.

      • monitorIdstring | nullRequired

        The one monitor the window covers; null covers the whole type

      • namestringRequired
      • startsAtintegerRequired

        Epoch milliseconds

      • endsAtintegerRequired

        Epoch milliseconds

      • endedEarlyAtinteger | nullRequired

        When the window was ended early; null while it runs its course

      • suppressAlertsbooleanRequired
      • showOnStatusPagebooleanRequired
      • createdAtintegerRequired

        Epoch milliseconds

      • updatedAtintegerRequired

        Epoch milliseconds

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123", {
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
	},
});
let result = await response.json();

Response

json
{
	"data": {
		"maintenanceWindow": {
			"id": "mnt_abc123",
			"teamId": "team_xyz789",
			"monitorType": "http",
			"monitorId": "mon_def456",
			"name": "Database Migration",
			"startsAt": 1771120800000,
			"endsAt": 1771128000000,
			"endedEarlyAt": null,
			"suppressAlerts": true,
			"showOnStatusPage": true,
			"createdAt": 1771063200000,
			"updatedAt": 1771063200000
		}
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z"
	}
}

PATCH /api/v1/maintenance/:id

Updates an existing maintenance window with a JSON merge patch.

Required scope: maintenance:write

Request Body

Include only the fields you want to change. null clears the scope and resets suppressAlerts and showOnStatusPage to true; name, startsAt and endsAt cannot be removed.

  • namestring

    Name of the maintenance window (at least 1 character)

  • startsAtstring

    Start time in ISO 8601 format

  • endsAtstring

    End time in ISO 8601 format (must be after the window's start, sent or stored)

  • monitorTypestring | null

    The kind of monitor the window is limited to: http, dns, tcp, cron or flow

  • monitorIdstring | null

    The single monitor the window is limited to, or null for all monitors

  • suppressAlertsboolean | null

    Whether to suppress alerts during maintenance; null resets it to true

  • showOnStatusPageboolean | null

    Whether to show maintenance on status page; null resets it to true

monitorType and monitorId are the window's scope, and they move as a pair: change either one and both are rewritten, so narrowing a window to a whole kind of monitor cannot leave the previous monitor's id behind it. Mention neither and the scope is left exactly as it is.

  • {"monitorType": "dns"} — every DNS monitor

  • {"monitorType": "dns", "monitorId": "..."} — that one DNS monitor

  • {"monitorId": null} or {"monitorType": null} — back to team-wide

  • {"monitorId": "..."} — that one HTTP monitor

A monitorId that does not belong to the team, or that belongs to a different kind of monitor than monitorType names, answers a 404 not-found problem.

Update With PUT

PUT /api/v1/maintenance/:id takes the same fields, for integrations written before PATCH existed. A field you leave out keeps its value, and null is refused everywhere except monitorId, where it widens the window back to team-wide. Sending either scope field rewrites both, and the window's endsAt must still follow its startsAt.

Required scope: maintenance:write

Errors (4)
StatusTypeMeaning
400validation-errorThe request failed validation
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
404not-foundThe resource does not exist
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • maintenanceWindowobjectRequired
      Show nested fields
      • idstringRequired
      • teamIdstringRequired
      • monitorTypestring | nullRequired

        Monitor type the window covers; null covers every type One of http, dns, tcp, cron, flow.

      • monitorIdstring | nullRequired

        The one monitor the window covers; null covers the whole type

      • namestringRequired
      • startsAtintegerRequired

        Epoch milliseconds

      • endsAtintegerRequired

        Epoch milliseconds

      • endedEarlyAtinteger | nullRequired

        When the window was ended early; null while it runs its course

      • suppressAlertsbooleanRequired
      • showOnStatusPagebooleanRequired
      • createdAtintegerRequired

        Epoch milliseconds

      • updatedAtintegerRequired

        Epoch milliseconds

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl -X PATCH https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "name": "Extended Database Migration",
    "endsAt": "2026-02-15T06:00:00Z"
  }'
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123", {
	method: "PATCH",
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
		"Content-Type": "application/merge-patch+json",
	},
	body: JSON.stringify({
		"name": "Extended Database Migration",
		"endsAt": "2026-02-15T06:00:00Z"
	}),
});
let result = await response.json();

Response

json
{
	"data": {
		"maintenanceWindow": {
			"id": "mnt_abc123",
			"teamId": "team_xyz789",
			"monitorType": "http",
			"monitorId": "mon_def456",
			"name": "Extended Database Migration",
			"startsAt": 1771120800000,
			"endsAt": 1771135200000,
			"endedEarlyAt": null,
			"suppressAlerts": true,
			"showOnStatusPage": true,
			"createdAt": 1771063200000,
			"updatedAt": 1771068600000
		}
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z"
	}
}

DELETE /api/v1/maintenance/:id

Deletes a maintenance window.

Required scope: maintenance:write

Errors (4)
StatusTypeMeaning
400validation-errorThe request failed validation
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
404not-foundThe resource does not exist
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • deletedtrueRequired
  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl -X DELETE https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123", {
	method: "DELETE",
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
	},
});
let result = await response.json();

Response

json
{
	"data": {
		"deleted": true
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z"
	}
}

POST /api/v1/maintenance/:id/end

Ends a maintenance window early. Sets the endedEarlyAt timestamp to the current time.

Required scope: maintenance:write

Errors (4)
StatusTypeMeaning
400validation-errorThe request failed validation
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
404not-foundThe resource does not exist
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • maintenanceWindowobjectRequired
      Show nested fields
      • idstringRequired
      • teamIdstringRequired
      • monitorTypestring | nullRequired

        Monitor type the window covers; null covers every type One of http, dns, tcp, cron, flow.

      • monitorIdstring | nullRequired

        The one monitor the window covers; null covers the whole type

      • namestringRequired
      • startsAtintegerRequired

        Epoch milliseconds

      • endsAtintegerRequired

        Epoch milliseconds

      • endedEarlyAtinteger | nullRequired

        When the window was ended early; null while it runs its course

      • suppressAlertsbooleanRequired
      • showOnStatusPagebooleanRequired
      • createdAtintegerRequired

        Epoch milliseconds

      • updatedAtintegerRequired

        Epoch milliseconds

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl -X POST https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123/end \
  -H "Authorization: Bearer uptime_your_api_key"
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123/end", {
	method: "POST",
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
	},
});
let result = await response.json();

Response

json
{
	"data": {
		"maintenanceWindow": {
			"id": "mnt_abc123",
			"teamId": "team_xyz789",
			"monitorType": "http",
			"monitorId": "mon_def456",
			"name": "Database Migration",
			"startsAt": 1771120800000,
			"endsAt": 1771128000000,
			"endedEarlyAt": 1771125300000,
			"suppressAlerts": true,
			"showOnStatusPage": true,
			"createdAt": 1771063200000,
			"updatedAt": 1771125300000
		}
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z"
	}
}

Response Fields

FieldTypeDescription
idstringUnique maintenance window identifier
teamIdstringTeam that owns this maintenance window
monitorTypestring | nullKind of monitor the window is limited to, or null if it applies to every kind
monitorIdstring | nullAssociated monitor ID, or null if applies to all monitors
namestringDisplay name of the maintenance window
startsAtintegerScheduled start time as a Unix timestamp in milliseconds
endsAtintegerScheduled end time as a Unix timestamp in milliseconds
endedEarlyAtinteger | nullWhen maintenance was ended early, in milliseconds, or null
suppressAlertsbooleanWhether alerts are suppressed during maintenance
showOnStatusPagebooleanWhether maintenance is displayed on the status page
createdAtintegerCreation time as a Unix timestamp in milliseconds
updatedAtintegerLast update time as a Unix timestamp in milliseconds
Documentation