Manage maintenance windows for Splunk Cloud Platform

The Admin Config Service (ACS) API lets you perform certain maintenance window management tasks for your Splunk Cloud platform deployment on a self-service basis. You can currently use the ACS API to view both historic and upcoming maintenance window schedule information.

ACS supports viewing of maintenance window schedule information only. It does not support scheduling of maintenance windows.

For more information on Splunk Cloud Platform maintenance windows, see Splunk Cloud Platform Service Details.

Requirements

To view maintenance window information using the ACS API:

• You must have the sc_admin role.
• You must have Splunk Cloud Platform version 8.0.2007 or higher.
• Your deployment must have one or more separate search heads or a search head cluster. ACS is not supported on single instance deployments.

The ACS API does not support maintenance window operations on FedRAMP deployments.

Set up the ACS API

Before using the ACS API, you must download the ACS Open API 3.0 specification, which includes the parameters, response codes, and other data you need to work with the ACS API. You must also create an authentication token in Splunk Cloud Platform for use with ACS endpoint requests. For details on how to set up the ACS API to manage maintenance windows, see Set up the ACS API.

View maintenance window schedules

You can use the ACS API to view both historic and upcoming maintenance window schedule information for your Splunk Cloud Platform deployment.

Maintenance window schedule data is updated daily, not in real time.

List maintenance windows

To list scheduled maintenance windows for your deployment, send an HTTP GET request to the /maintenance-windows/schedules endpoint. By default, the request returns a list of maintenance windows scheduled within +/-30 days from now.

You can optionally specify the following query parameters to customize the time frame and the number of listed maintenance windows:

Parameter	Description
fromTime	The earliest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).
toTime	The latest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).
count	Number of maintenance window schedules. Default value is 30.
nextLink	The start time of the next scheduled maintenance window relative to the current maintenance window count. For example, if there are 3 total scheduled maintenance windows and the count is set to 2, the request returns a nextLink value stating the start time of the 3rd maintenance window. This is used for pagination purposes. A value of null indicates there are no more pages.

If fromTime and toTime are not set, the request returns +30 days from now. If only fromTime is set, it returns +30 days from fromTime. If only toTime is set, it returns -30 days until toTime. If both are set it returns from fromTime to toTime.

For example:

curl -X GET 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/schedules?fromTime=2022-08-09&toTime=2022-08-14&nextLink=2022-08-21T04:00:00Z&count=1' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu …'

The request returns information about the scheduled maintenance windows within the specified time frame. For example:

{
   "nextLink": "2024-08-21T04:00:00Z",
   "schedules": [
       {
           "duration": "2h",
           "lastModifiedTimestamp": "2024-06-20T04:00:00Z",
           "lastSummary": "Customer requested an upgrade",
           "mwType": "Service Update Maintenance",
           "operations": [
               {
                   "SFDCTickets": ["SFDC-1234"],
                   "endTime": "2024-08-21T06:00:00Z",
                   "notes": ["Updating the stack to the latest version."],
                   "operationDescription": "KitKat Tock Upgradtez",
                   "operationStatus": "Tentative",
                   "operationType": "Splunk Upgrade",
                   "startTime": "2024-08-21T04:00:00Z",
                   "targetVersion": "9.1.2308.207",
                   "zeroDowntime": true
               }
           ],
           "requestedEntity": "splunk",
           "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
           "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
           "status": "Tentative",
           "zeroDowntime": true
       }
   ]
}

The maintenance-windows/schedules endpoint only lists historical maintenance windows that have completed. The endpoint does not list previously scheduled maintenance windows that have been canceled.

For endpoint details, see maintenance-windows/schedules in the ACS endpoint reference.

Describe individual maintenance windows

To describe a specific maintenance window, send an HTTP GET request to the /maintenance-windows/schedules/{scheduleId} endpoint, specifying the maintenance window schedule ID. For example:

curl -X GET 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/schedules/{scheduleId}' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu …'

The request returns information about the specific maintenance window. For example:

{
    "duration": "2h",
    "lastModifiedTimestamp": "2024-06-20T04:00:00Z",
    "lastSummary": "Customer requested an upgrade",
    "mwType": "Service Update Maintenance",
    "operations": [
        {
            "SFDCTickets": ["SFDC-1234"],
            "endTime": "2024-08-21T06:00:00Z",
            "notes": ["Updating the stack to the latest version."],
            "operationDescription": "KitKat Tock Upgradtez",
            "operationStatus": "Tentative",
            "operationType": "Splunk Upgrade",
            "startTime": "2024-08-21T04:00:00Z",
            "targetVersion": "9.1.2308.207",
            "zeroDowntime": true
        }
    ],
    "requestedEntity": "splunk",
    "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
    "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
    "status": "Tentative",
    "zeroDowntime": true
}

For endpoint details, see maintenance-windows/schedules/{scheduleId} in the ACS endpoint reference.

Audit maintenance windows

To view an audit trail of status changes for a specific maintenance window, send an HTTP request to the maintenance-windows/schedules/{scheduleID}/audits endpoint, specifying the maintenance window schedule ID.

By default, the request returns a list of all audit events for the specified maintenance window. You can optionally specify the following fromTime and toTime query parameters to view a subset of audit events within a specified time frame:

Parameter	Description
fromTime	The earliest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).
toTime	The latest time the maintenance window schedule starts. Acceptable format is YYYY-MM-DD or in RFC3339 (YYYY-MM--DDTHH:mm:SSZHH:mm).

For example:

curl -X GET 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/schedules/{scheduleId}/audits?fromTime=2022-08-09&toTime=2022-08-14' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsu …'

The request returns a list of all audit events within the specified time frame. For example:

{
    "audits": [
        {
            "duration": "2h",
            "lastModifiedTimestamp": "2024-06-20T04:00:00Z",
            "lastSummary": "Customer requested an upgrade",
            "mwType": "Service Update Maintenance",
            "operations": [
                {
                    "SFDCTickets": ["SFDC-1234"],
                    "endTime": "2024-08-21T06:00:00Z",
                    "notes": ["Updating the stack to the latest version."],
                    "operationDescription": "KitKat Tock Upgrade",
                    "operationStatus": "Tentative",
                    "operationType": "Splunk Upgrade",
                    "startTime": "2024-08-21T04:00:00Z",
                    "targetVersion": "9.1.2308.207",
                    "zeroDowntime": true
                }
            ],
            "requestedEntity": "splunk",
            "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
            "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
            "status": "Tentative",
            "zeroDowntime": true
        },
        {
            "duration": "2h",
            "lastModifiedTimestamp": "2024-06-22T08:00:00Z",
            "lastSummary": "Customer requested an upgrade",
            "mwType": "Service Update Maintenance",
            "operations": [
                {
                    "SFDCTickets": ["SFDC-1234"],
                    "endTime": "2024-08-21T06:00:00Z",
                    "notes": ["Updating the stack to the latest version."],
                    "operationDescription": "KitKat Tock Upgrade",
                    "operationStatus": "Scheduled",
                    "operationType": "Splunk Upgrade",
                    "startTime": "2024-08-21T04:00:00Z",
                    "targetVersion": "9.1.2308.207",
                    "zeroDowntime": true
                }
            ],
            "requestedEntity": "splunk",
            "scheduleId": "1e4729b4-11d0-4165-a886-a21cce7139f2",
            "scheduleStartTimestamp": "2024-08-21T04:00:00Z",
            "status": "Tentative",
            "zeroDowntime": true
        }
    ]
}

For endpoint details, see maintenance-windows/schedules/{scheduleID}/audits in the ACS endpoint reference.

Manage maintenance window preferences

The ACS API lets you manage certain maintenance window preferences for your Splunk Cloud Platform deployment.

ACS currently supports management of maintenance window change freeze preferences only.

You can use the ACS API to list, create, update, and delete maintenance window change freeze requests.

To learn more, see the Splunk Cloud Platform maintenance policy and the Maintenance section in the Splunk Cloud Platform Service Details.

View maintenance window change freeze requests

You can use the ACS API to list all change freeze requests made for your deployment.

To list all change freezes, send an HTTP GET request to the maintenance-windows/preferences endpoint. For example:

curl -X GET "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences" \
--header "Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI..."

The response shows all customer- and Splunk-initiated change freeze requests, regardless of date, including upcoming change freeze requests.

{
	"changeFreezes":{
		"customerInitiatedFreezes":[
			{
				"appliesTo":"Customer and Splunk Initiated Changes",
				"createdTimestamp":"2023-01-08T22:00:57Z",
				"endDate":"2023/02/14",
				"id":"b84a41c4-0344-48e5-8008-33ed44c2d393",
				"lastModifiedTimestamp":"2023-01-08T22:00:57Z",
				"reason":"Customer Business Needs",
				"startDate":"2023/02/01"
			}
		],
		"splunkInitiatedFreezes":[
			{
				"appliesTo":"Customer and Splunk Initiated Changes",
				"category":"Professional Services",
				"createdTimestamp":"2023-01-08T22:00:57Z",
				"endDate":"2023/04/05",
				"id":"c5c122ee-78fc-4b4e-be6d-737396913abb",
				"lastModifiedTimestamp":"2023-01-08T22:00:57Z",
				"reason":"Professional Services Engagement",
				"startDate":"2023/04/01"
			}
		]
	},
	"recordVersion":19
}

Error response (400, 404, 500):

{
	"code": "400-bad-request",
	"message": "<error message from server>"
}

All times are UTC.

For endpoint details, see maintenance-windows/preferences in the ACS endpoint reference.

Update maintenance window change freeze requests

You can use the ACS API to update maintenance window change freeze requests.

ACS supports update of customer-initiated change freezes only.

To update a maintenance window change freeze, send an HTTP PUT request to the maintenance-windows/preferences endpoint, specifying the following parameters in the request body:

Parameter	Description
id	ID of the change freeze
startDate	Start date of the change freeze, format: YYYY/MM/DD (UTC). Change freezes start at 00:00 UTC on the start date.
endDate	End date of the change freeze, format: YYYY/MM/DD (UTC). Change freezes end at 23:59 UTC on the end date.
appliesTo	Types of maintenance window changes to which the change freeze applies: Splunk Initiated Changes Only Customer and Splunk Initiated Changes
reason	Reason for this change freeze request.
recordVersion	Version of the record used to handle write conflicts. To obtain this value, send a GET request to the maintenance-windows/preferences endpoint prior to sending a PUT request. The recordVersion value that you specify in the PUT request must match the value in the latest GET request. See View maintenance window change freeze requests.

For example:

curl -X PUT 'https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences' \
--header 'Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI...' \
--data '{
	"changeFreezes": {
		"customerInitiatedFreezes": [
			{
				"startDate": "2024/06/28",
				"endDate": "2024/07/02",
				"id": "b84a41c4-0344-48e5-8008-33ed44c2d393",
				"appliesTo": "Splunk Initiated Changes Only",
				"reason": "End of Quarter Freeze"
			},
			{
				"startDate": "2024/09/01",
				"endDate": "2024/09/14",
				"id": "3200242e-afc8-41dd-acd4-13ef41b5f3fd",
				"appliesTo": "Customer and Splunk Initiated Changes",
				"reason": "Business Needs"
			},
		]
	},
	"recordVersion": 2
}'

A successful request returns a 204 (no content) code.

You must include all existing change freeze requests with their associated ID value in the PUT request body. Omitting an existing change freeze from the PUT request deletes that change freeze request. See Delete an existing change freeze request.

When updating change freeze requests using the ACS API, note the following:

• You can only update changes freezes in the customerInitiatedFreezes list. Updates to change freezes in the splunkInitiatedFreezes list are not allowed.
• Change freeze IDs uniquely identify a change freeze in the customerInitiatedFreezes list.
• You cannot specify a change freeze ID. Splunk Cloud Platform automatically generates change freeze IDs.
• Adding a change freeze without an ID creates a new change freeze with a unique ID. See Create a new change freeze request.

Create a new change freeze request

Before you can create a new change freeze request, you must obtain the change freeze recordVersion number. To do so, send an HTTP GET request to the maintenance-windows/preferences endpoint. Find the recordVersion value in the response. For example:

{
	"changeFreezes": {
		"customerInitiatedFreezes": [],
		"splunkInitiatedFreezes": []
	},
	"recordVersion": 1
}

To create a new change freeze request, send an HTTP PUT request to the maintenance-windows/preferences endpoint, specifying the recordVersion value, but omitting the "id" field from the request body. For example:

curl -X PUT "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences" \
--header "Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI..."
--data '{
	"changeFreezes": {
		"customerInitiatedFreezes": [
			{
				"startDate": "2024/06/28",
				"endDate": "2024/07/02",
				"appliesTo": "Splunk Initiated Changes Only",
				"reason": "End of Quarter Freeze"
			},
		]
	},
	"recordVersion": 1
}'

The PUT request creates a new change freeze with a unique ID. To confirm creation of the new change freeze, send a GET request to the maintenance-windows/preferences endpoint. The response includes the new change freeze with a unique ID. For example:

{
	"changeFreezes": {
		"customerInitiatedFreezes": [
			{
				"appliesTo": "Splunk Initiated Changes Only",
				"createdTimestamp": "2024-04-18T00:29:25Z"
				"endDate": "2024/07/02",
				"id": "95f6242e-b4a8-4f72-9e38-bbf7ec6cac56",
				"lastModifiedTimestamp": "2024-04-18T00:29:25Z",
				"reason": "End of Quarter Freeze",
				"startDate": "2024/06/28",
				"tickets": []
			}
		],
		"splunkInitiatedFreezes": []
	},
	"recordVersion": 2
}

You cannot create an in-progress change freeze that specifies startDate in the past and endDate in the future.

Delete an existing change freeze request

Before you can delete a change freeze request, you must obtain the change freeze recordVersion number. To do so, send an HTTP GET request to the maintenance-windows/preferences endpoint. Find the recordVersion value in the response. For example:

{
	"changeFreezes": {
		"customerInitiatedFreezes": [
			{
				"appliesTo": "Splunk Initiated Changes Only",
				"createdTimestamp": "2024-04-18T00:29:25Z",
				"endDate": "2024/07/02",
				"id": "95f6242e-b4a8-4f72-9e38-bbf7ec6cac56",
				"lastModifiedTimestamp": "2024-04-18T00:29:25Z",
				"reason": "End of Quarter Freeze",
				"startDate": "2024/06/28",
				"tickets": []
			}
		],
		"splunkInitiatedFreezes": []
	},
	"recordVersion": 2
}

To delete the change freeze, send an HTTP PUT request to the maintenance-windows/preferences endpoint, specifying the recordVersion value, but omitting the specific change freeze object from the request body. For example:

curl -X PUT "https://admin.splunk.com/{stack}/adminconfig/v2/maintenance-windows/preferences" \
--header "Authorization: Bearer eyJraWQiOiJzcGx1bmsuc2VjcmV0IiwiYWxnI..."
--data '{
	"changeFreezes": {
		"customerInitiatedFreezes": [],
	},
	"recordVersion": 2
}'

You cannot delete a change freeze that has ended.

Deleting an ongoing change freeze ends that change freeze at the current time.

For endpoint details, see maintenance-windows/preferences in the ACS endpoint reference.

For detailed information on maintenance window change freeze policies, see Splunk Cloud Platform maintenance policy.