Scheduled maintenance

Download schema

Planned maintenance announced on a status page. While it is in progress, its components show as under maintenance. An automatic maintenance starts and completes on schedule by itself; a manual one changes when you set its status. Subscribers are emailed when it is scheduled, starts and completes.

List scheduled maintenance

GET

https://api.spectate.net/v1

/status-pages/{statusPage}/maintenances

Returns the page's maintenance, the latest planned start first.

List scheduled maintenance › path Parameters

statusPage

string · uuid · required

Status page ID.

List scheduled maintenance › query Parameters

page

integer

Page number, from 1.

Default: 1

per_page

integer

Maintenances per page, 1 to 100.

Default: 25

filter[status]

ScheduledMaintenanceStatus · enum

Only maintenance with this status.

Where a scheduled maintenance stands.


`scheduled` Announced, not started yet.
`in_progress` Going on: its components show as under maintenance.
`completed` Over.

Enum values:

scheduled

in_progress

completed

List scheduled maintenance › Responses

Paginated set of ScheduledMaintenance

current_page

integer · min: 1 · required

ScheduledMaintenance[] · required

first_page_url

string | null · required

from

integer | null · min: 1 · required

last_page_url

string | null · required

last_page

integer · min: 1 · required

object[] · required

Generated paginator links.

next_page_url

string | null · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

prev_page_url

string | null · required

to

integer | null · min: 1 · required

Number of the last item in the slice.

total

integer · min: 0 · required

Total number of items being paginated.

GET/status-pages/{statusPage}/maintenances

curl https://api.spectate.net/v1/status-pages/:statusPage/maintenances \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "current_page": 1,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "title": "Database upgrade",
      "description": "The API is read-only for about ten minutes.",
      "status": "scheduled",
      "automatic": true,
      "scheduled_at": "2024-08-25T15:00:00Z",
      "scheduled_until": "2024-08-25T15:00:00Z",
      "started_at": "2024-08-25T15:00:00Z",
      "completed_at": "2024-08-25T15:00:00Z",
      "affected_components": [
        {
          "component": {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "API"
          },
          "impact": "none"
        }
      ],
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "first_page_url": "first_page_url",
  "from": 1,
  "last_page_url": "last_page_url",
  "last_page": 1,
  "links": [
    {
      "url": "url",
      "label": "label",
      "active": true
    }
  ],
  "next_page_url": "next_page_url",
  "path": "path",
  "per_page": 0,
  "prev_page_url": "prev_page_url",
  "to": 1,
  "total": 0
}

json

application/json

Schedule maintenance

POST

https://api.spectate.net/v1

/status-pages/{statusPage}/maintenances

Announces it on the page and emails confirmed subscribers unless notify_subscribers is false. scheduled_at must be in the future.

Schedule maintenance › path Parameters

statusPage

string · uuid · required

Status page ID.

Schedule maintenance › Request Body

Maintenance to announce on a status page.

CreateScheduledMaintenance

title

string · maxLength: 255 · required

Title shown on the page, up to 255 characters

Example: Database upgrade

scheduled_at

string · date-time · required

Planned start, in the future

description

string | null

What happens and what visitors notice, in Markdown; null for none

Example: The API is read-only for about ten minutes.

scheduled_until

string | null · date-time

Planned end, after scheduled_at; null for none

automatic

boolean

true (default): starts at scheduled_at and completes at scheduled_until by itself (without a planned end, complete it by setting status). false: only changes when you set status

StatusPageAffectedComponentInput[]

Components it affects; components of the status page only

notify_subscribers

boolean

Email confirmed subscribers about it (default true)

Schedule maintenance › Responses

The new maintenance.

Planned maintenance announced on a status page. While it is in progress its components show as under maintenance.

ScheduledMaintenance

id

string · uuid · required

Maintenance ID

title

string · required

Title shown on the page

Example: Database upgrade

description

string | null · required

What happens and what visitors notice, in Markdown; null for none

Example: The API is read-only for about ten minutes.

status

ScheduledMaintenanceStatus · enum · required

Where it stands


`scheduled` Announced, not started yet.
`in_progress` Going on: its components show as under maintenance.
`completed` Over.

Enum values:

scheduled

in_progress

completed

automatic

boolean · required

true: starts at scheduled_at and completes at scheduled_until by itself (without a planned end it is completed by hand). false: only changes when you set status

scheduled_at

string · date-time · required

Planned start

scheduled_until

string | null · date-time · required

Planned end; null for none

started_at

string | null · date-time · required

When it actually went in progress; null before

completed_at

string | null · date-time · required

When it completed; null before

StatusPageAffectedComponent[] · required

Components it affects

created_at

string · date-time · required

When it was created

POST/status-pages/{statusPage}/maintenances

curl https://api.spectate.net/v1/status-pages/:statusPage/maintenances \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "automatic": true,
  "affected_components": [
    {
      "component_id": "00000000-0000-0000-0000-000000000000",
      "impact": "none"
    }
  ],
  "notify_subscribers": true
}'

Example Request Body

{
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "automatic": true,
  "affected_components": [
    {
      "component_id": "00000000-0000-0000-0000-000000000000",
      "impact": "none"
    }
  ],
  "notify_subscribers": true
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "status": "scheduled",
  "automatic": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "started_at": "2024-08-25T15:00:00Z",
  "completed_at": "2024-08-25T15:00:00Z",
  "affected_components": [
    {
      "component": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "API"
      },
      "impact": "none"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Get scheduled maintenance

GET

https://api.spectate.net/v1

/status-pages/{statusPage}/maintenances/{maintenance}

Returns the maintenance with the components it affects.

Get scheduled maintenance › path Parameters

statusPage

string · uuid · required

Status page ID.

maintenance

string · uuid · required

Maintenance ID.

Get scheduled maintenance › Responses

The maintenance.

Planned maintenance announced on a status page. While it is in progress its components show as under maintenance.

ScheduledMaintenance

id

string · uuid · required

Maintenance ID

title

string · required

Title shown on the page

Example: Database upgrade

description

string | null · required

What happens and what visitors notice, in Markdown; null for none

Example: The API is read-only for about ten minutes.

status

ScheduledMaintenanceStatus · enum · required

Where it stands


`scheduled` Announced, not started yet.
`in_progress` Going on: its components show as under maintenance.
`completed` Over.

Enum values:

scheduled

in_progress

completed

automatic

boolean · required

true: starts at scheduled_at and completes at scheduled_until by itself (without a planned end it is completed by hand). false: only changes when you set status

scheduled_at

string · date-time · required

Planned start

scheduled_until

string | null · date-time · required

Planned end; null for none

started_at

string | null · date-time · required

When it actually went in progress; null before

completed_at

string | null · date-time · required

When it completed; null before

StatusPageAffectedComponent[] · required

Components it affects

created_at

string · date-time · required

When it was created

GET/status-pages/{statusPage}/maintenances/{maintenance}

curl https://api.spectate.net/v1/status-pages/:statusPage/maintenances/:maintenance \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "status": "scheduled",
  "automatic": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "started_at": "2024-08-25T15:00:00Z",
  "completed_at": "2024-08-25T15:00:00Z",
  "affected_components": [
    {
      "component": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "API"
      },
      "impact": "none"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Update scheduled maintenance

PATCH

https://api.spectate.net/v1

/status-pages/{statusPage}/maintenances/{maintenance}

Changes only the fields you send; affected_components replaces the list. Setting status to in_progress or completed (or setting completed_at) emails confirmed subscribers unless notify_subscribers is false; other changes are silent.

Update scheduled maintenance › path Parameters

statusPage

string · uuid · required

Status page ID.

maintenance

string · uuid · required

Maintenance ID.

Update scheduled maintenance › Request Body

Changes to a maintenance; fields left out keep their value.

UpdateScheduledMaintenance

title

string · maxLength: 255

Title shown on the page, up to 255 characters

Example: Database upgrade

description

string | null

What happens and what visitors notice, in Markdown; null for none

Example: The API is read-only for about ten minutes.

status

ScheduledMaintenanceStatus · enum

Move it along by hand: in_progress starts it, completed completes it (stamping completed_at), scheduled puts it back


`scheduled` Announced, not started yet.
`in_progress` Going on: its components show as under maintenance.
`completed` Over.

Enum values:

scheduled

in_progress

completed

automatic

boolean

true: starts and completes on schedule. false: only changes when you set status

scheduled_at

string · date-time

Planned start

scheduled_until

string | null · date-time

Planned end; null for none

completed_at

string | null · date-time

When it completed. Setting it completes the maintenance

StatusPageAffectedComponentInput[]

Components it affects; replaces the current list. Components of the status page only

notify_subscribers

boolean

Email confirmed subscribers when this starts or completes the maintenance (default true)

Update scheduled maintenance › Responses

The updated maintenance.

Planned maintenance announced on a status page. While it is in progress its components show as under maintenance.

ScheduledMaintenance

id

string · uuid · required

Maintenance ID

title

string · required

Title shown on the page

Example: Database upgrade

description

string | null · required

What happens and what visitors notice, in Markdown; null for none

Example: The API is read-only for about ten minutes.

status

ScheduledMaintenanceStatus · enum · required

Where it stands


`scheduled` Announced, not started yet.
`in_progress` Going on: its components show as under maintenance.
`completed` Over.

Enum values:

scheduled

in_progress

completed

automatic

boolean · required

true: starts at scheduled_at and completes at scheduled_until by itself (without a planned end it is completed by hand). false: only changes when you set status

scheduled_at

string · date-time · required

Planned start

scheduled_until

string | null · date-time · required

Planned end; null for none

started_at

string | null · date-time · required

When it actually went in progress; null before

completed_at

string | null · date-time · required

When it completed; null before

StatusPageAffectedComponent[] · required

Components it affects

created_at

string · date-time · required

When it was created

PATCH/status-pages/{statusPage}/maintenances/{maintenance}

curl https://api.spectate.net/v1/status-pages/:statusPage/maintenances/:maintenance \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "status": "scheduled",
  "automatic": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "completed_at": "2024-08-25T15:00:00Z",
  "affected_components": [
    {
      "component_id": "00000000-0000-0000-0000-000000000000",
      "impact": "none"
    }
  ],
  "notify_subscribers": true
}'

Example Request Body

{
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "status": "scheduled",
  "automatic": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "completed_at": "2024-08-25T15:00:00Z",
  "affected_components": [
    {
      "component_id": "00000000-0000-0000-0000-000000000000",
      "impact": "none"
    }
  ],
  "notify_subscribers": true
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "Database upgrade",
  "description": "The API is read-only for about ten minutes.",
  "status": "scheduled",
  "automatic": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "scheduled_until": "2024-08-25T15:00:00Z",
  "started_at": "2024-08-25T15:00:00Z",
  "completed_at": "2024-08-25T15:00:00Z",
  "affected_components": [
    {
      "component": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "API"
      },
      "impact": "none"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Delete scheduled maintenance

DELETE

https://api.spectate.net/v1

/status-pages/{statusPage}/maintenances/{maintenance}

It disappears from the page and its components go back to their other status. Silent: subscribers aren't emailed.

Delete scheduled maintenance › path Parameters

statusPage

string · uuid · required

Status page ID.

maintenance

string · uuid · required

Maintenance ID.

Delete scheduled maintenance › Responses

No content

No data returned

Status page components Status page incidents