Start team maintenance

Starts team-wide maintenance, which pauses all monitors, heartbeats and integrations in a team, for example around a deploy. Set how long it lasts with either duration or until. On a team already in maintenance, the request moves the end to the new time.

Your team's Slack and Microsoft Teams integrations are notified when maintenance starts and when it ends, as when you start it in Better Stack.

An Incidents API token acts on its own team. With a global API token, pick the team with team_name or team_id. Read-only tokens can't start maintenance.

PUT https://incidents.betterstack.com/api/v2/team-maintenance

Headers

Authorization
required string
Content-Type
required string

Body parameters

duration
integer
until
string
team_name
string
team_id
string
200

Response body

{
  "data": {
    "id": "t123",
    "type": "team_maintenance",
    "attributes": {
      "team_name": "Platform team",
      "maintenance": true,
      "maintenance_to": "2026-11-16T18:30:00Z"
    }
  }
}
401

Response body

{
  "errors": "Invalid Team API token. How to find your Team API token: https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-an-incidents-api-token"
}
403

Response body

{
  "errors": "This API token is read-only and cannot be used for write operations."
}
422

Response body

{
  "errors": "Pass exactly one of `duration` (seconds) or `until` (an ISO 8601 time)."
}
422

Response body

{
  "errors": "This token has access to multiple teams. Please use `team_name` or `better_stack_team_id` to specify the team"
}

Response attributes

id
string
type
string
attributes.team_name
string
attributes.maintenance
boolean
attributes.maintenance_to
string or null

Example cURL

For 30 minutes Until a time
curl --request PUT \
  --url https://incidents.betterstack.com/api/v2/team-maintenance \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "duration": 1800
  }'
curl --request PUT \
  --url https://incidents.betterstack.com/api/v2/team-maintenance \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "until": "2026-11-16T18:30:00Z",
    "team_name": "Platform team"
  }'