To add a new monitor blackout or recipient blackout, send a POST request to /blackouts, with a JSON body containing the blackout configuration.

To create multiple blackouts at once, use Bulk Edit Blackouts instead.

Request URL

POST https://api.alertsite.com/api/v3/blackouts

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 containing the blackout configuration (see Blackout Object). The monitor or recipient to be blacked out is specified by assoc_id.

Blackouts can be one-time or recurring (persistent = true).

One-time blackouts require from_date and thru_date set in the future. You cannot add past blackouts.
Recurring blackouts require start_date, start_time, end_day, and end_time.

The persistent property may be omitted, in which case it will be inferred from other properties. For example, if from_date and thru_date are provided (which are specific to one-time blackouts), persistent is assumed to be false.

Examples

Create a one-time blackout for monitor # 123456:

{
  "assoc_id": 123456,
  "type": "Monitor",
  "persistent": false,
  "from_date": "2019-01-15 13:00:00",
  "thru_date": "2019-01-15 15:30:00",
  "note": "Scheduled maintenance"
}

Create a recurring recipient blackout that would disable recipient #145632 on weekends:

{
  "assoc_id": 145632,
  "type": "Notifier",
  "persistent": true,
  "start_day": 6,
  "start_time": "00:00",
  "end_day": 7,
  "end_time": "23:59"
}

Response body

On success, the operation returns HTTP status 200 with the ID of the created blackout:

{
"id": "123456"
}

Error responses have a non-200 status code and contain the errors list, such as:

{
  "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 creates a one-time blackout for monitor 123456. 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
monitor_id = 123456

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

blackout_params = {
  'assoc_id': monitor_id,
  'type': 'Monitor',
  'persistent': False,
  'from_date': start_time.strftime('%Y-%m-%d %H:%M:%S'),
  'thru_date': end_time.strftime('%Y-%m-%d %H:%M:%S'),
  'note': 'Scheduled maintenance'
}

# 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']

# Create a blackout
headers = {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
}
r = requests.post(baseUrl + '/blackouts', data=json.dumps(blackout_params), headers=headers)
result = r.json()
if r.status_code == requests.codes.ok:
    blackout_id = result['id']
    print('Successfully created a blackout. ID: {}'.format(blackout_id))
else:
    print('Could not create a blackout. The following error(s) occurred:', *result['errors'], sep='\n')

Create Blackout