Edit blackouts for one or several monitors specified by the monitors list. You can edit one-time blackouts, recurring (persistent) blackouts, or both. The new blackouts can be either appended to existing ones, or replace the existing blackouts.

Request URL

POST https://api.alertsite.com/api/v3/blackouts/bulk-edit

Authentication

The request must include the Authorization header containing a user’s access token:

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

Request body

The request body is a JSON object that looks as follows:

{
  "monitors": [
    123456,
    231978
  ],

  "update_one_time": true,
  "update_one_time_action": "append",
  "one_time_blackouts": [
    {
      "from_date": "2018-11-06 13:00:00",
      "thru_date": "2018-11-06 15:30:00",
      "type": "Monitor",
      "note": "Scheduled maintenance"
    }
  ],

  "update_persistent": true,
  "update_persistent_action": "append",
  "persistent_blackouts": [
    {
      "start_day": 7,
      "start_time": "20:00",
      "end_day": 7,
      "end_time": "22:15",
      "type": "Monitor"
    }
  ]
}

The monitors field is a list of monitor IDs whose blackouts you want to change. If one of the monitor IDs is invalid, the request will fail with HTTP status 403 and blackouts will not be updated.

To update one-time blackouts, specify the following fields:

update_one_time = true;
update_one_time_action - can be append (add to existing blackouts) or update (replace existing blackouts);
one_time_blackouts - an array of one-time blackouts. See Blackout Object for a description of the data fields used.

To update recurring blackouts, specify the following fields:

update_persistent = true;
update_persistent_action - can be append (add to existing blackouts) or update (replace existing blackouts);
persistent_blackouts - an array of recurring blackouts. See Blackout Object for a description of the data fields used.

Note: The request must include both update_one_time and update_persistent fields with the appropriate boolean values (true/false) even if you edit only one-time blackouts or only recurring blackouts.

Response body

On success, the operation returns HTTP status 200 with the following response body:

{
"success": true
}

Error responses have HTTP status in the 4xx range and contain the errors list, for example:

{
  "errors": [
    {
      "code": 400,
      "message": "invalid_request - User authentication failed."
    }
  ]
}

Try it out

Click here to test this operation in AlertSite’s interactive API console.

Code examples

This code adds a one-time blackout to monitors 123456 and 312102. The blackout will begin in an hour from now and last for one hour.

Python

# Python 3.5+
import requests  # Requests library http://docs.python-requests.org
import json
from datetime import datetime, timedelta

baseUrl = 'https://api.alertsite.com/api/v3'
username = '[email protected]'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password
monitors = [123456, 312102]

# Blackout will start an hour from now and last an hour
start_time = datetime.now() + timedelta(hours=1)
end_time = start_time + timedelta(hours=1)

blackout_params = {
    'monitors': monitors,
    'update_one_time': True,
    'update_one_time_action': 'append',
    'one_time_blackouts': [
        {
            'from_date': start_time.strftime('%Y-%m-%d %H:%M:%S'),
            'thru_date': end_time.strftime('%Y-%m-%d %H:%M:%S'),
            'type': 'Monitor',
            'note': 'Scheduled maintenance'
        }
    ],
    'update_persistent': False
}

# Log in
payload = {'username': username, 'password': password}
r = requests.post(baseUrl + '/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']

# Bulk edit monitor blackouts
headers = {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
}
r = requests.post(baseUrl + '/blackouts/bulk-edit', data=json.dumps(blackout_params), headers=headers)

if r.status_code == requests.codes.ok:
    print('Successfully updated monitor blackouts.')
else:
    print('Could not bulk edit monitor blackouts. The following error(s) occurred:', *r.json()['errors'], sep='\n')

Bulk Edit Monitor Blackouts