Schedule maintenance

POST/workspaces/{workspace}/status/maintenance

Schedules a maintenance window. Times are sent as local wall-clock times in the time zone you choose and stored in UTC.

Authentication

Send an API token as a bearer token. This endpoint needs a read and write token, made by an editor, admin or owner. Create one in My account → API tokens; see scopes and roles.

Authorization: Bearer 42|bynh_pat_•••••••Header

Path parameters

workspacestringRequired
Your workspace slug, e.g. dokan.

Request body

application/json

titlestringRequiredmax 160
“Name the work, like “Database upgrade”.”
bodystring, nullablemax 5000
Details.
starts_atstringRequiredY-m-d\TH:i (e.g. 2026-10-16T02:00)
Local wall-clock time in timezone; must be in the future.
ends_atstringRequiredY-m-d\TH:i
After starts_at, at most 7 days later.
timezonestringRequired
Any PHP time zone identifier, e.g. Asia/Riyadh.
component_idsstringRequired
1–50 distinct components of this workspace.
notify_subscribersbooleanRequired
Email subscribers about this window.
notify_nowbooleandefault false
Announce it now (only if notify_subscribers).
notify_day_beforebooleandefault true
notify_startbooleandefault true
notify_endbooleandefault true
pause_alertsbooleandefault true

Response

201 Created

The window.

idintegerWindow id.
titlestringTitle.
bodystring|nullDetails.
starts_atstringUTC, ISO 8601.
ends_atstringUTC, ISO 8601.
timezonestringZone the times were entered in.
duration_minutesintegerLength.
statusenumStage. One of scheduled, in_progress, completed, cancelled.
status_labelstringLocalized.
notify_subscribersbooleanMaster switch for subscriber emails.
notify_nowbooleanAnnounce when scheduled.
notify_day_beforebooleanRemind the day before.
notify_startbooleanEmail at start.
notify_endbooleanEmail at end.
pause_alertsbooleanDon’t alert on affected monitors during the window.
components[]{id, name}Affected components.

Rate limits

This endpoint counts toward your general limit of 120 requests a minute. When you go over, wait for the number of seconds in Retry-After.

Errors

401The token is missing, wrong, revoked or expired.

403The token is read-only (message: “This token is read-only. Create a read and write token to make changes.”). Or: The token’s owner is a viewer (“Viewers can read everything but can’t change it.”), or the workspace’s editing is paused (a billing message, e.g. “Your trial has ended, so editing is paused. …”).

404The token belongs to another workspace, or its owner is no longer a member.

422“Name the work…”, “Pick when the window starts.”, “Pick when the window ends.”, “Pick at least one component this affects.”, “Pick a time zone from the list.”, “The window has to end after it starts.”, “Pick a start time in the future.”, “Keep a window to 7 days or less. Split longer work into several.”

Every error is JSON with a message. See Errors.

Next →Change maintenance

curl -X POST "https://api.bynh.io/api/v1/workspaces/dokan/status/maintenance" \ -H "Authorization: Bearer $BYNH_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "title": "Database upgrade", "body": "Checkout may be unavailable for up to 20 minutes while we upgrade the database.", "starts_at": "2026-10-16T02:00", "ends_at": "2026-10-16T03:00", "timezone": "Asia/Riyadh", "component_ids": [ 2 ], "notify_subscribers": true, "notify_now": true }'

{ "data": { "id": 8, "title": "Database upgrade", "body": "Checkout may be unavailable for up to 20 minutes while we upgrade the database.", "starts_at": "2026-10-15T23:00:00+00:00", "ends_at": "2026-10-16T00:00:00+00:00", "timezone": "Asia/Riyadh", "duration_minutes": 60, "status": "scheduled", "status_label": "Scheduled", "notify_subscribers": true, "notify_now": true, "notify_day_before": true, "notify_start": true, "notify_end": true, "pause_alerts": true, "components": [ { "id": 2, "name": "Checkout" } ] } }