Suppressions

Suppressions enable you to suspend alarm notifications for a set period of time. A single suppression can apply to any number of alarms. For example, you would use one suppression to suppress all alarm notifications during a scheduled maintenance period this week and another suppression for some expected downtime the following week. When creating a suppression, you specify the following:

  • A timestamp at which to start the suppression (specified as milliseconds since the Unix epoch in UTC). You can use 0 to represent now.
  • A timestamp at which to end the suppression (specify as milliseconds since the Unix epoch in UTC). You can use 0 to represent now.
  • At least one of the following: a list of notification plans (specified by ID), a list of entities (specified by ID), a list of checks (specified by entityID:checkID), a list of alarms (specified by entityID:alarmID).

Attributes

NameDescriptionValidation
alarmsA list of alarm IDs (e.g. “enFooBar:alAbc123”) for determining notification suppression. Optional

Array [String,Non-empty string]

* Array or object with number of items between 0 and 512
checksA list of check IDs (e.g. “enFooBar:chAbc123”) for determining notification suppression. Optional

Array [String,Non-empty string]

* Array or object with number of items between 0 and 512
end_timeThe Unix timestamp in milliseconds that the suppression will end. Specify 0 to use the current time. Optional

Integer
entitiesA list of entity IDs for determining notification suppression. Optional

Array [String,Non-empty string]

* Array or object with number between 0 and 512
labelA friendly label for a suppression. Optional

String between 1 and 255 characters long
notification_plansA list of notification plan IDs for determining notification suppression. Optional

Array [String,Non-empty string]

* Array or object with number of items between 0 and 512
start_timeThe Unix timestamp in milliseconds that the suppression will start. Specify 0 to use the current time. Optional

Integer

Use the following suppressions API operations to create, view, update, and manage suppression templates.

Create suppression

POST /suppressions

Creates a new suppression.

Specify the characteristics for the suppression using a valid set of parameters from the suppressions attributes table.

The different lists (notification_plans, entities, checks, and alarms) represent the different levels at which suppressions can be defined. When creating a suppression, carefully consider which scopes you want to use in order to avoid accidentally suppressing an alarm you did not mean to.

Note

When creating a suppression, the start_time can only be set to 0 or a time in the future. There is some wiggle room allocated to account for the time it takes to receive and process a request, meaning that if the start_time is less than 60 seconds in the past, it will be considered to be now instead of causing a validation error. If you want the suppression to begin immediately, set the start_time to 0.

The following table shows the possible response codes for this operation:

Response CodeNameDescription
201OKThe ‘Location’ header contains a link to the newly created suppression.
400Bad requestThe system received an invalid value in a request.
401UnauthorizedThe system received a request from a user that is not authenticated.
403ForbiddenThe system received a request that the user is not authorized to make.
500Internal Server ErrorAn unexpected condition was encountered.
503Service UnavailableThe system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

NameTypeDescription
X-Auth-TokenString (Required)A valid authentication token with administrative access. For details, see Get your credentials

Example: Suppress notifications for alarms on check ch123 on entity en123 using the notification plan npfooBar

{
"notification_plans": ["npfooBar"],
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Example: Suppress notifications for entity en123 for all notification plans

{
"entities": ["en123"],
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Example: Suppress only check ch123 on entity en123 for all notification plans

{
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Example: Suppress all notifications for entity enMonkey and notifications for check ch123 on entity en123 for all notification plans

{
"entities": ["enMonkey"],
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Example: Suppress all notifications for notification plan npTechnical

{
"notification_plans": ["npTechnical"],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Example: Suppress alarm al123 on entity en123 and alarm alBaz on entity enMonkey for the notification plan npTechnical

{
"notification_plans": ["npTechnical"],
"alarms": ["en123:al123", "enMonkey:alBaz"],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Response

This operation does not return a response body.

List suppressions

GET /suppressions

Lists the suppressions. Use /supressions?id=supressionOneId & id=supressionTwoId to filter the results to only include information about the specified suppressions.

This operation can be paginated. For information, see Paginated collections.

The following table shows the possible response codes for this operation:

Response CodeNameDescription
200OKRequest completed.
401UnauthorizedThe system received a request from a user that is not authenticated.
403ForbiddenThe system received a request that the user is not authorized to make.
500Internal Server ErrorAn unexpected condition was encountered.
503Service UnavailableThe system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

NameTypeDescription
X-Auth-TokenString (Required)A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

Example List Suppressions: JSON response

{
"values": [
{
"id": "spAAAAA",
"notification_plans": ['npfooBar'],
"entities": [],
"checks": ['en123:ch123'],
"alarms": [],
"start_time": 1378492433027,
"end_time": 1378492433027
}
],
"metadata": {
"count": 1,
"limit": 50,
"marker": null,
"next_marker": null,
"next_href": null
}
}

Get a suppression by ID

GET /suppressions/{suppressionId}

This operation returns the suppression specified by the suppressionId.

The following table shows the possible response codes for this operation:

Response CodeNameDescription
200OKRequest completed.
401UnauthorizedThe system received a request from a user that is not authenticated.
403ForbiddenThe system received a request that the user is not authorized to make.
404Not FoundThe URL, entity, or account requested is not found in the system.
500Internal Server ErrorAn unexpected condition was encountered.
503Service UnavailableThe system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

NameTypeDescription
X-Auth-TokenString (Required)A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

Example Get suppression by ID: JSON response

{
"id": "spAAAAA",
"notification_plans": ['npfooBar'],
"entities": [],
"checks": ['en123:ch123'],
"alarms": [],
"start_time": 1378492433027,
"end_time": 1378492433027
}

Update a suppression

PUT /suppressions/{suppressionId}

Updates the suppression specified by the suppressionId.

You can complete partial updates for a suppression. When you submit the request only include values for the attributes you want to update. The values on omitted parameters are not updated. Note that updating a list completely replaces the previous list. Refer to the suppressions attributes table.

Note

Keep the following points in mind when updating a suppression:

  • Until the start_time, you can modify any field on the suppression; however, after that time has passed and the suppression has begun only the end_time can be updated.
  • The end_time can only be set to 0 or a time in the future. As with the start_time, there is an allowance of 60 seconds made to account for the time it takes to receive and process a request. This means that if the provided end_time is less than 60 seconds in the past, it will be considered to be now instead of causing a validation error. If you want the suppression to end immediately, set the end_time to 0.

The following table shows the possible response codes for this operation:

Response CodeNameDescription
204No ContentThe server has fulfilled the request. Does not return a response body.
400Bad requestThe system received an invalid value in a request.
401UnauthorizedThe system received a request from a user that is not authenticated.
403ForbiddenThe system received a request that the user is not authorized to make.
404Not FoundThe URL, entity, or account requested is not found in the system.
500Internal Server ErrorAn unexpected condition was encountered.
503Service UnavailableThe system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

NameTypeDescription
X-Auth-TokenString (Required)A valid authentication token with administrative access. For details, see Get your credentials

Example Update suppression: JSON request

{
"entities": ["en234"],
"end_time": 1378495433027
}

Response

This operation does not return a response body.

Delete suppression

DELETE /suppressions/{suppressionId}

Delete a suppression from your account.

Note

You can delete a suppression at any point, even while it is active. If an active suppression is deleted, it ends immediately.

The following table shows the possible response codes for this operation:

Response CodeNameDescription
204No ContentThe server has fulfilled the request. Does not return a response body.
401UnauthorizedThe system received a request from a user that is not authenticated.
403ForbiddenThe system received a request that the user is not authorized to make.
404Not FoundThe URL, entity, or account requested is not found in the system.
500Internal Server ErrorAn unexpected condition was encountered.
503Service UnavailableThe system is experiencing heavy load or another system failure.

Request

The following table shows the header parameters for the request:

NameTypeDescription
X-Auth-TokenString (Required)A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response

This operation does not return a response body.