IBM Cloud API Docs

Introduction

API for loading and editing notification policies that are used to match the alerts and direct notifications to the appropriate recipients.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Methods

listPolicies

List the name and description for all notification policies

GET /policies/v1

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Response

Status Code

  • Successful request

  • Invalid request

  • Unauthorized

  • Not authorized

Example responses
  • [
      {
        "name": "MyPolicy",
        "description": "This is a test policy.",
        "enabled": true,
        "policyURI": "https://localhost:3001/api/policies/v1/MyPolicy"
      },
      {
        "name": "Sample Notification Policy",
        "description": "Sample notification policy that sends notifications for all incoming alerts",
        "enabled": false,
        "policyURI": "https://localhost:3001/api/policies/v1/Sample%20Notification%20Policy"
      }
    ]

createPolicy

Creates a notification policy

POST /policies/v1

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Notification policy payload

Response

Status Code

  • Policy successfully created

  • Invalid request

  • Unauthorized

  • Not authorized

No Sample Response

This method does not specify any sample responses.

replacePolicy

Replace the policy with the policy payload provided.

PUT /policies/v1/{name}

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy name

Notification policy payload

Response

Status Code

  • Successful request

  • See other

  • Policy was not updated

  • Unauthorized

  • Not authorized

  • Unable to locate policy

No Sample Response

This method does not specify any sample responses.

getPolicyById

Gets a policy

GET /policies/v1/{name}

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy name

Response

Status Code

  • Successful request

  • Unauthorized

  • Not authorized

  • Unable to locate policy

Example responses
  • {
      "enabled": true,
      "name": "MyPolicy",
      "description": "This is a test policy.",
      "users": [
        "myuser@myco.com"
      ],
      "groups": [
        "MyGroup"
      ],
      "channels": [
        {
          "type": "Slack",
          "name": "General"
        }
      ],
      "webhooks": [
        "MyWebhook"
      ],
      "rules": [
        {
          "description": "My Custom Rule",
          "inputs": {
            "attribute": "What",
            "operator": "CONTAINS",
            "value": "Failure"
          }
        }
      ],
      "matchAllRules": true,
      "delayNotifications": {
        "until": 3,
        "within": 60
      },
      "notifyWhen": "EveryMatch",
      "escalations": [
        {
          "waitFor": 20,
          "timeUnits": "minutes",
          "users": [
            "myboss@myco.com"
          ],
          "groups": [
            "MyBosses"
          ],
          "channels": [
            {
              "type": "Slack",
              "name": "General"
            }
          ],
          "webhooks": [
            "MyEscalationWebhook"
          ]
        }
      ],
      "notificationExceptions": [
        {
          "rules": [
            {
              "description": "My Custom Rule",
              "inputs": {
                "attribute": "What",
                "operator": "CONTAINS",
                "value": "Failure"
              }
            }
          ],
          "matchAllRules": true,
          "notifyBy": [
            "email"
          ]
        }
      ]
    }

deletePolicyById

Deletes a policy

DELETE /policies/v1/{name}

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy identifier

Response

Status Code

  • Successful request

  • Unauthorized

  • Not authorized

  • Unable to locate policy

  • Error deleting policy

No Sample Response

This method does not specify any sample responses.

addUsers

Add one or more users as recipients for the specified notification policy

POST /policies/v1/{name}/users

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy identifier

    Possible values: length ≥ 1

Query Parameters

  • User name(s) to add to the policy as notification recipients

    Possible values: number of items ≥ 1, contains only unique items

Response

Status Code

  • Successful request

  • See other

  • No users were added

  • Unauthorized

  • Not authorized

  • Unable to locate policy

No Sample Response

This method does not specify any sample responses.

removeUsers

Remove one or more users as recipients for the specified notification policy

DELETE /policies/v1/{name}/users

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy identifier

    Possible values: length ≥ 1

Query Parameters

  • User name(s) to remove from the policy as notification recipients

    Possible values: number of items ≥ 1, contains only unique items

Response

Status Code

  • Successful request

  • See other

  • No users were removed

  • Unauthorized

  • Not authorized

  • Unable to locate policy

No Sample Response

This method does not specify any sample responses.

addGroups

Add one or more groups as recipients for the specified notification policy

POST /policies/v1/{name}/groups

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy identifier

Query Parameters

  • Group name(s) to add to the policy as notification recipients

    Possible values: number of items ≥ 1, contains only unique items

Response

Status Code

  • Successful request

  • See other

  • No groups were added

  • Unauthorized

  • Not authorized

  • Unable to locate policy

No Sample Response

This method does not specify any sample responses.

removeGroups

Remove one or more groups as recipients for the specified notification policy

DELETE /policies/v1/{name}/groups

Request

Custom Headers

  • Allowable values: [application/json,text/plain]

Path Parameters

  • Policy identifier

Query Parameters

  • Group name(s) to remove from the policy as notification recipients

    Possible values: number of items ≥ 1, contains only unique items

Response

Status Code

  • Successful request

  • See other

  • No groups were removed

  • Unauthorized

  • Not authorized

  • Unable to locate policy

No Sample Response

This method does not specify any sample responses.