Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Maintenance windows API

6 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/maintenance-windows

List maintenance windows

Scheduled maintenance, latest start first.

ParameterInTypeDescription
phasequeryenum: upcoming | active | pastupcoming: not started; active: running; past: ended or canceled
pageIdquerystring (uuid)Only windows posted to this status page
cursorquerystringOpaque cursor from a previous page's nextCursor
limitqueryinteger (int64)Page size (default 50, max 200)
Response 200 · OK · application/json
PageMaintenanceWindowView
  • MaintenanceWindowView[] | nullrequired
  • nextCursorstring
    Present when more items exist
Errors
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/maintenance-windows

Schedule a maintenance window

While the window is active its services are in maintenance: no uptime alerts, and their checks are left out of the availability. The pages it is posted to announce it from 14 days ahead. 422 invalid_window unless endsAt is after startsAt, window_in_past when it ends in the past. Requires the admin scope.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
Request body · application/json · required
CreateMaintenanceInputBody
  • descriptionstring
  • endsAtstring (date-time)required
    After startsAt and in the future
  • pageIdsstring[] | null
    The status pages that announce it
  • serviceIdsstring[] | null
    The services in maintenance while the window is active
  • startsAtstring (date-time)required
  • titlestringrequired
Response 201 · Created · application/json
MaintenanceWindowView
  • canceledAtstring (date-time) | nullrequired
  • createdAtstring (date-time)required
  • descriptionstringrequired
  • endsAtstring (date-time)required
  • idstringrequired
  • pageIdsstring[] | nullrequired
    The status pages that announce the window
  • phaseenum: upcoming | active | ended | canceledrequired
  • serviceIdsstring[] | nullrequired
    The services in maintenance while it is active: no uptime alerts, excluded from availability
  • startsAtstring (date-time)required
  • titlestringrequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entityinvalid_window
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/maintenance-windows/{windowId}

Get a maintenance window

ParameterInTypeDescription
windowIdrequiredpathstring
Response 200 · OK · application/json
MaintenanceWindowView
  • canceledAtstring (date-time) | nullrequired
  • createdAtstring (date-time)required
  • descriptionstringrequired
  • endsAtstring (date-time)required
  • idstringrequired
  • pageIdsstring[] | nullrequired
    The status pages that announce the window
  • phaseenum: upcoming | active | ended | canceledrequired
  • serviceIdsstring[] | nullrequired
    The services in maintenance while it is active: no uptime alerts, excluded from availability
  • startsAtstring (date-time)required
  • titlestringrequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/maintenance-windows/{windowId}

Update a maintenance window

Omitted fields stay. 409 window_ended / window_canceled for a window that is over. Requires the admin scope.

ParameterInTypeDescription
windowIdrequiredpathstring
Request body · application/json · required
UpdateMaintenanceInputBody
  • descriptionstring
  • endsAtstring (date-time)
  • pageIdsstring[] | null
    Replaces the pages; [] clears them
  • serviceIdsstring[] | null
    Replaces the services; [] clears them
  • startsAtstring (date-time)
  • titlestring
Response 200 · OK · application/json
MaintenanceWindowView
  • canceledAtstring (date-time) | nullrequired
  • createdAtstring (date-time)required
  • descriptionstringrequired
  • endsAtstring (date-time)required
  • idstringrequired
  • pageIdsstring[] | nullrequired
    The status pages that announce the window
  • phaseenum: upcoming | active | ended | canceledrequired
  • serviceIdsstring[] | nullrequired
    The services in maintenance while it is active: no uptime alerts, excluded from availability
  • startsAtstring (date-time)required
  • titlestringrequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictwindow_ended
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/maintenance-windows/{windowId}

Delete a maintenance window

Deletes the window. Requires the admin scope.

ParameterInTypeDescription
windowIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/maintenance-windows/{windowId}/cancel

Cancel a maintenance window

Ends the window now (sets canceledAt): its services leave maintenance and the pages stop announcing it. Canceling a canceled window changes nothing; 409 window_ended for one that has already ended. Requires the admin scope.

ParameterInTypeDescription
windowIdrequiredpathstring
Response 200 · OK · application/json
MaintenanceWindowView
  • canceledAtstring (date-time) | nullrequired
  • createdAtstring (date-time)required
  • descriptionstringrequired
  • endsAtstring (date-time)required
  • idstringrequired
  • pageIdsstring[] | nullrequired
    The status pages that announce the window
  • phaseenum: upcoming | active | ended | canceledrequired
  • serviceIdsstring[] | nullrequired
    The services in maintenance while it is active: no uptime alerts, excluded from availability
  • startsAtstring (date-time)required
  • titlestringrequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictwindow_ended
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.