# Start team maintenance

Starts [team-wide maintenance](https://betterstack.com/docs/uptime/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](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-an-incidents-api-token) acts on its own team. With a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token), pick the team with `team_name` or `team_id`. Read-only tokens can't start maintenance.

[endpoint]
base_url = "https://incidents.betterstack.com"
path = "/api/v2/team-maintenance"
method = "PUT"

[[body_param]]
name = "duration"
description = "How long the maintenance lasts from now, in seconds, for example `1800` for 30 minutes, and at most 1000 years, which is what **indefinitely** sets in Better Stack. Use either `duration` or `until`."
required = false
type = "integer"

[[body_param]]
name = "until"
description = "When the maintenance ends, as an ISO 8601 time in the future, like `2026-11-16T18:30:00Z`, and at most 1000 years from now. Use either `duration` or `until`."
required = false
type = "string"

[[body_param]]
name = "team_name"
description = "The name of the team. Required with a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) that reaches several teams, unless you set `team_id`."
required = false
type = "string"

[[body_param]]
name = "team_id"
description = "The ID of the team shown in Better Stack URLs, with the `t` prefix, like `t123`. Use it instead of `team_name` with a global API token."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns the team's maintenance state.'''
body = '''{
  "data": {
    "id": "t123",
    "type": "team_maintenance",
    "attributes": {
      "team_name": "Platform team",
      "maintenance": true,
      "maintenance_to": "2026-11-16T18:30:00Z"
    }
  }
}'''

[[response]]
status = 401
description = '''Authentication failed due to a missing or invalid token.'''
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"
}'''

[[response]]
status = 403
description = '''Returned for a read-only token.'''
body = '''{
  "errors": "This API token is read-only and cannot be used for write operations."
}'''

[[response]]
status = 422
description = '''Returned when the request sets both or neither of `duration` and `until`, or an invalid value.'''
body = '''{
  "errors": "Pass exactly one of `duration` (seconds) or `until` (an ISO 8601 time)."
}'''

[[response]]
status = 422
description = '''Returned when a global API token reaches several teams and the request doesn't pick one.'''
body = '''{
  "errors": "This token has access to multiple teams. Please use `team_name` or `better_stack_team_id` to specify the team"
}'''
[/responses]

[params]
title = "Response attributes"

[[param]]
name = "id"
type = "string"
description = "The ID of the team, like `t123`."

[[param]]
name = "type"
type = "string"
description = "Always `team_maintenance`."

[[param]]
name = "attributes.team_name"
type = "string"
description = "The name of the team."

[[param]]
name = "attributes.maintenance"
type = "boolean"
description = "Whether the team is in maintenance now."

[[param]]
name = "attributes.maintenance_to"
type = "string or null"
description = "When the maintenance ends, in ISO 8601 format, or `null` when the team isn't in maintenance."
[/params]

#### Example cURL

[code-tabs]
```shell
[label For 30 minutes]
curl --request PUT \
  --url https://incidents.betterstack.com/api/v2/team-maintenance \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "duration": 1800
  }'
```
```shell
[label 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 '{
    "until": "2026-11-16T18:30:00Z",
    "team_name": "Platform team"
  }'
```
[/code-tabs]
