• Home
  • Dynatrace API
  • Configuration
  • Maintenance windows
  • POST a maintenance window

Maintenance windows API - POST a maintenance window

This API is deprecated. Use the Settings API with the Maintenance windows (builtin:alerting.maintenance-window) schema instead.

Creates a new maintenance window.

The request consumes and produces an application/json payload.

POSTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows
SaaShttps://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows

Authentication

To execute this request, you need an access token with WriteConfig scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

The body must not provide an ID. An ID is assigned automatically by Dynatrace.

ParameterTypeDescriptionInRequired
bodyMaintenanceWindow

The JSON body of the request. Contains parameters of the new maintenance window.

bodyoptional

Request body objects

The MaintenanceWindow object

Configuration of a maintenance window.

ElementTypeDescriptionRequired
metadataConfigurationMetadata

Metadata useful for debugging

optional
idstring

The ID of the maintenance window.

optional
namestring

The name of the maintenance window, displayed in the UI.

required
descriptionstring

A short description of the maintenance purpose.

required
typestring

The type of the maintenance: planned or unplanned.

The element can hold these values
  • PLANNED
  • UNPLANNED
required
suppressionstring

The type of suppression of alerting and problem detection during the maintenance.

The element can hold these values
  • DETECT_PROBLEMS_AND_ALERT
  • DETECT_PROBLEMS_DONT_ALERT
  • DONT_DETECT_PROBLEMS
required
suppressSyntheticMonitorsExecutionboolean

Suppress execution of synthetic monitors during the maintenance.

optional
scopeScope

The scope of the maintenance window.

The scope restricts the alert/problem detection suppression to certain Dynatrace entities. It can contain a list of entities and/or matching rules for dynamic formation of the scope.

If no scope is specified, the alert/problem detection suppression applies to the entire environment.

optional
scheduleSchedule

The schedule of the maintenance window.

required

The ConfigurationMetadata object

Metadata useful for debugging

ElementTypeDescriptionRequired
configurationVersionsinteger[]

A sorted list of the version numbers of the configuration.

optional
currentConfigurationVersionsstring[]

A sorted list of version numbers of the configuration.

optional
clusterVersionstring

Dynatrace version.

optional

The Scope object

The scope of the maintenance window.

The scope restricts the alert/problem detection suppression to certain Dynatrace entities. It can contain a list of entities and/or matching rules for dynamic formation of the scope.

If no scope is specified, the alert/problem detection suppression applies to the entire environment.

ElementTypeDescriptionRequired
entitiesstring[]

A list of Dynatrace entities (for example, hosts or services) to be included in the scope.

Allowed values are Dynatrace entity IDs.

required
matchesMonitoredEntityFilter[]

A list of matching rules for dynamic scope formation.

If several rules are set, the OR logic applies.

required

The MonitoredEntityFilter object

A matching rule for Dynatrace entities.

ElementTypeDescriptionRequired
typestring

The type of the Dynatrace entities (for example, hosts or services) you want to pick up by matching.

The element can hold these values
  • APM_SECURITY_GATEWAY
  • APPLICATION
  • APPLICATION_METHOD
  • APPLICATION_METHOD_GROUP
  • APPMON_SERVER
  • APPMON_SYSTEM_PROFILE
  • AUTO_SCALING_GROUP
  • AUXILIARY_SYNTHETIC_TEST
  • AWS_APPLICATION_LOAD_BALANCER
  • AWS_AVAILABILITY_ZONE
  • AWS_CREDENTIALS
  • AWS_LAMBDA_FUNCTION
  • AWS_NETWORK_LOAD_BALANCER
  • AZURE_API_MANAGEMENT_SERVICE
  • AZURE_APPLICATION_GATEWAY
  • AZURE_APP_SERVICE_PLAN
  • AZURE_COSMOS_DB
  • AZURE_CREDENTIALS
  • AZURE_EVENT_HUB
  • AZURE_EVENT_HUB_NAMESPACE
  • AZURE_FUNCTION_APP
  • AZURE_IOT_HUB
  • AZURE_LOAD_BALANCER
  • AZURE_MGMT_GROUP
  • AZURE_REDIS_CACHE
  • AZURE_REGION
  • AZURE_SERVICE_BUS_NAMESPACE
  • AZURE_SERVICE_BUS_QUEUE
  • AZURE_SERVICE_BUS_TOPIC
  • AZURE_SQL_DATABASE
  • AZURE_SQL_ELASTIC_POOL
  • AZURE_SQL_SERVER
  • AZURE_STORAGE_ACCOUNT
  • AZURE_SUBSCRIPTION
  • AZURE_TENANT
  • AZURE_VM
  • AZURE_VM_SCALE_SET
  • AZURE_WEB_APP
  • BROWSER
  • CF_APPLICATION
  • CF_FOUNDATION
  • CINDER_VOLUME
  • CLOUD_APPLICATION
  • CLOUD_APPLICATION_INSTANCE
  • CLOUD_APPLICATION_NAMESPACE
  • CLOUD_NETWORK_INGRESS
  • CLOUD_NETWORK_POLICY
  • CONTAINER_GROUP
  • CONTAINER_GROUP_INSTANCE
  • CUSTOM_APPLICATION
  • CUSTOM_DEVICE
  • CUSTOM_DEVICE_GROUP
  • DCRUM_APPLICATION
  • DCRUM_SERVICE
  • DCRUM_SERVICE_INSTANCE
  • DEVICE_APPLICATION_METHOD
  • DEVICE_APPLICATION_METHOD_GROUP
  • DISK
  • DOCKER_CONTAINER_GROUP
  • DOCKER_CONTAINER_GROUP_INSTANCE
  • DYNAMO_DB_TABLE
  • EBS_VOLUME
  • EC2_INSTANCE
  • ELASTIC_LOAD_BALANCER
  • ENVIRONMENT
  • EXTERNAL_SYNTHETIC_TEST_STEP
  • GCP_ZONE
  • GEOLOCATION
  • GEOLOC_SITE
  • GOOGLE_COMPUTE_ENGINE
  • HOST
  • HOST_GROUP
  • HTTP_CHECK
  • HTTP_CHECK_STEP
  • HYPERVISOR
  • HYPERVISOR_CLUSTER
  • HYPERVISOR_DISK
  • KUBERNETES_CLUSTER
  • KUBERNETES_NODE
  • KUBERNETES_SERVICE
  • MOBILE_APPLICATION
  • MULTIPROTOCOL_MONITOR
  • NETWORK_INTERFACE
  • NEUTRON_SUBNET
  • OPENSTACK_PROJECT
  • OPENSTACK_REGION
  • OPENSTACK_VM
  • OS
  • PROCESS_GROUP
  • PROCESS_GROUP_INSTANCE
  • QUEUE
  • QUEUE_INSTANCE
  • RELATIONAL_DATABASE_SERVICE
  • S3BUCKET
  • SERVICE
  • SERVICE_INSTANCE
  • SERVICE_METHOD
  • SERVICE_METHOD_GROUP
  • SWIFT_CONTAINER
  • SYNTHETIC_LOCATION
  • SYNTHETIC_TEST
  • SYNTHETIC_TEST_STEP
  • VCENTER
  • VIRTUALMACHINE
  • VMWARE_DATACENTER
optional
mzIdstring

The ID of a management zone to which the matched entities must belong.

optional
tagsTagInfo[]

The tag you want to use for matching.

You can use custom tags from the UI, AWS tags, Cloud Foundry tags, OpenShift/Kubernetes, and tags based on environment variables.

required
tagCombinationstring

The logic that applies when several tags are specified: AND/OR.

If not set, the OR logic is used.

The element can hold these values
  • AND
  • OR
optional

The TagInfo object

Tag of a Dynatrace entity.

ElementTypeDescriptionRequired
contextstring

The origin of the tag, such as AWS or Cloud Foundry.

Custom tags use the CONTEXTLESS value.

The element can hold these values
  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_CLOUD
  • KUBERNETES
required
keystring

The key of the tag.

Custom tags have the tag value here.

required
valuestring

The value of the tag.

Not applicable to custom tags.

optional

The Schedule object

The schedule of the maintenance window.

ElementTypeDescriptionRequired
recurrenceTypestring

The type of the schedule recurrence.

The element can hold these values
  • DAILY
  • MONTHLY
  • ONCE
  • WEEKLY
required
recurrenceRecurrence

The recurrence of the maintenance window.

optional
startstring

The start date and time of the maintenance window validity period in yyyy-mm-dd HH:mm format.

required
endstring

The end date and time of the maintenance window validity period in yyyy-mm-dd HH:mm format.

required
zoneIdstring

The time zone of the start and end time. Default time zone is UTC.

You can use either UTC offset UTC+01:00 format or the IANA Time Zone Database format (for example, Europe/Vienna).

required

The Recurrence object

The recurrence of the maintenance window.

ElementTypeDescriptionRequired
dayOfWeekstring

The day of the week for weekly maintenance.

The format is the full name of the day in upper case, for example THURSDAY.

The element can hold these values
  • FRIDAY
  • MONDAY
  • SATURDAY
  • SUNDAY
  • THURSDAY
  • TUESDAY
  • WEDNESDAY
optional
dayOfMonthinteger

The day of the month for monthly maintenance.

The value of 31 is treated as the last day of the month for months that don't have a 31st day. The value of 30 is also treated as the last day of the month for February.

optional
startTimestring

The start time of the maintenance window in HH:mm format.

required
durationMinutesinteger

The duration of the maintenance window in minutes.

required

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

json
{ "metadata": { "configurationVersions": [ 4, 2 ], "clusterVersion": "Mock version" }, "name": "Example Window", "description": "An example Maintenance window", "type": "UNPLANNED", "suppression": "DETECT_PROBLEMS_AND_ALERT", "suppressSyntheticMonitorsExecution": "true", "scope": { "entities": [ "HOST-0000000000123456" ], "matches": [ { "type": "HOST", "mzId": "123456789", "tags": [ { "key": "testkey", "value": "testvalue", "context": "AWS" } ], "tagCombination": "AND" } ] }, "schedule": { "recurrenceType": "MONTHLY", "recurrence": { "dayOfMonth": "23", "startTime": "16:28", "durationMinutes": "60" }, "start": "2018-08-02 00:00", "end": "2019-02-27 00:00", "zoneId": "Europe/Vienna" } }

Response

Response codes

CodeTypeDescription
201EntityShortRepresentation

Success. The new maintenance window has been created. The response body contains its ID.

400ErrorEnvelope

Failed. The input is invalid

Response body objects

The EntityShortRepresentation object

The short representation of a Dynatrace entity.

ElementTypeDescription
idstring

The ID of the Dynatrace entity.

namestring

The name of the Dynatrace entity.

descriptionstring

A short description of the Dynatrace entity.

Response body JSON model

json
{ "id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a", "name": "Dynatrace entity", "description": "Dynatrace entity for the REST API example" }

Validate payload

We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.

The request consumes an application/json payload.

POSTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows/validator
SaaShttps://{your-environment-id}.live.dynatrace.com/api/config/v1/maintenanceWindows/validator
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/config/v1/maintenanceWindows/validator

Authentication

To execute this request, you need an access token with WriteConfig scope.

To learn how to obtain and use it, see Tokens and authentication.

Response

Response codes

CodeTypeDescription
204

Validated. The submitted configuration is valid. Response doesn't have a body.

400ErrorEnvelope

Failed. The input is invalid

Example

In this example, the request creates a new maintenance window for a one-time planned maintenance. The maintenance window begins at 8:00 am and ends at 1:00 pm on July 31st, 2019. It affects the application with the ID of APPLICATION-61A89B82DF26BCFC and all the hosts that have the MainApp custom tag. Problem detection is suppressed during this maintenance.

The API token is passed in the Authorization header.

The request body is lengthy, so it is truncated in the Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own. Be sure to use the entity IDs and tags that are available in your environment. You can retrieve the list of monitored entities with the Topology and Smartscape API and the list of tags with the Automatically applied tags API.

Curl

bash
curl -X POST \ "https://mySampleEnv.live.dynatrace.com/api/config/v1/maintenanceWindows" \ -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \ -H 'Content-Type: application/json' \ -d '{ <truncated - see the Request body section > }'

Request URL

plaintext
https://mySampleEnv.live.dynatrace.com/api/config/v1/maintenanceWindows

Request body

json
{ "name": "Main app update", "description": "Deployment of a new version of the main application", "type": "PLANNED", "suppression": "DONT_DETECT_PROBLEMS", "scope": { "entities": ["APPLICATION-61A89B82DF26BCFC"], "matches": [ { "type": "HOST", "mzId": null, "tags": [ { "context": "CONTEXTLESS", "key": "MainApp" } ], "tagCombination": "OR" } ] }, "schedule": { "recurrenceType": "ONCE", "start": "2019-07-31 08:00", "end": "2019-07-31 13:00", "zoneId": "Europe/Vienna" } }

Response body

json
{ "id": "ac6f245d-e945-4e0c-85b1-8c134d0b05ad", "name": "Main app update", "description": "Deployment of a new version of the main app" }

Response code

201

Result

The new maintenance window looks like this in the UI:

POST example

Related topics
  • Maintenance windows

    Understand when to use a maintenance window. Read about the supported maintenance window types.