{"type":"api","title":"Create alert rule","meta":{"id":"/apps/pubhub/media/000-v7-apis/5b3454a4300b838cc17f7b2cdc0690fdd15058d5/9a54eafb-59ad-38f2-a440-c003b58ad29f","info":{"description":"You can manage the following alert functionalities on the ThousandEyes platform using the Alerts API:\n\n* **Alerts**: Retrieve alert details. Alerts are assigned to tests through alert rules.\n\n* **Alert Rules**: Conditions that you configure in order to highlight or be notified of events of interest in your ThousandEyes tests. When an alert rule’s conditions are met, the associated alert is triggered and the alert becomes active. It remains active until the alert is cleared. Alert rules are reusable across multiple tests..\n\n* **Alert Suppression Windows**: Suppress alerts for tests during periods such as planned maintenance. Windows can be one-time events or recurring events to handle periodic occurrences such as monthly downtime for maintenance.\n\nFor more information about the alerts, see [Alerts](https://docs.thousandeyes.com/product-documentation/alerts).\n","title":"Alerts API","version":"7.0.34"},"security":[{"BearerAuth":[]}],"tags":[{"name":"Alerts"},{"name":"Alert Rules"},{"name":"Alert Suppression Windows"}],"openapi":"3.0.1","servers":[{"description":"ThousandEyes API production URL","url":"https://api.thousandeyes.com/v7"}],"securitySchemes":{"BearerAuth":{"description":"Bearer authentication token","scheme":"bearer","type":"http"}}},"spec":{"description":"Creates a new alert rule in your account, using the provided POST data. The `Edit alert rules` permission is required to create an alert rule.\nNote: Assigning an alert rule to a test during creation requires the `Edit tests` permission.","operationId":"createAlertRule","parameters":[{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.","in":"query","name":"aid","required":false,"schema":{"example":"1234","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"ruleId":{"description":"Unique ID of the rule.","example":"127094","readOnly":true,"type":"string"},"ruleName":{"description":"Name of the alert rule.","example":"The End of the Internet","type":"string"},"expression":{"description":"The expression of the alert rule.","example":"((hops((hopDelay \u003e= 100 ms))))","type":"string"},"direction":{"description":"Direction for applicable alert types (eg. path trace, End-to-End (Agent) etc.)","enum":["to-target","from-target","bidirectional"],"example":"to-target","type":"string","$$ref":"#/components/schemas/AlertDirection"},"notifyOnClear":{"description":"Send notification when alert clears.","example":true,"type":"boolean"},"isDefault":{"description":"If set to `true`, this alert rule becomes the default for its test type and is automatically applied to newly created tests with relevant metrics. Only one default alert rule is allowed per test type.","example":true,"type":"boolean"},"alertType":{"description":"Type of alert being triggered. In multi-layered tests, this value represents the layer the alert relates to. See [Alert Details](https://developer.cisco.com/docs/thousandeyes/retrieve-alert-details/) documentation for a list of possible values","enum":["page-load","http-server","end-to-end-server","end-to-end-agent","voice","dns-server","dns-trace","dnssec","bgp","path-trace","ftp","sip-server","transactions","web-transactions","agent","network-outage","application-outage","device-device","device-interface","endpoint-network-server","endpoint-http-server","endpoint-path-trace","endpoint-browser-sessions-agent","endpoint-browser-sessions-application","api","web-transaction","unknown"],"example":"http-server","type":"string","$$ref":"#/components/schemas/AlertType"},"alertGroupType":{"description":"Category of alert type based on the application or network layer and source of the test.","enum":["bgp","browser-session","cloud-enterprise","endpoint"],"example":"endpoint","type":"string","$$ref":"#/components/schemas/AlertGroupType"},"minimumSources":{"description":"The minimum number of agents or monitors that must meet the specified criteria to trigger the alert.","example":10,"type":"integer"},"minimumSourcesPct":{"description":"The minimum percentage of all assigned agents or monitors that must meet the specified criteria to trigger the alert.","example":99,"type":"integer"},"roundsViolatingMode":{"description":"`exact` requires the same agents to meet the threshold in consecutive rounds. `auto` is only enabled for CEA and Endpoint Scheduled test rules. The default is `any`.","enum":["exact","any","auto"],"example":"exact","readOnly":true,"type":"string","$$ref":"#/components/schemas/AlertRoundsViolationMode"},"roundsViolatingOutOf":{"description":"Specifies the divisor (y value) in the “X of Y times” condition.","example":5,"type":"integer"},"roundsViolatingRequired":{"description":"Specifies the numerator (x value) in the “X of Y times” condition.","example":2,"type":"integer"},"includeCoveredPrefixes":{"description":"Set true to include covered prefixes in the BGP alert rule. Only applicable to BGP alert rules.","example":true,"type":"boolean"},"sensitivityLevel":{"description":"Used when `roundsViolatingMode` is set to `auto`. The default is `medium`. Higher sensitivity increases the likelihood of triggering alerts.","enum":["high","medium","low"],"example":"medium","readOnly":true,"type":"string","$$ref":"#/components/schemas/SensitivityLevel"},"severity":{"description":"The severity of the alert.","enum":["info","major","minor","critical","unknown"],"example":"major","type":"string","$$ref":"#/components/schemas/Severity"},"notifications":{"description":"Alert notification object. See Alert notification integrations.","properties":{"email":{"description":"Email notifications.","properties":{"recipients":{"description":"An array containing the email addresses to receive notifications.","example":["noreply@thousandeyes.com"],"items":{"type":"string"},"type":"array"},"message":{"description":"Custom text included in alert email notifications sent to recipients.","example":"Notification message","type":"string"}},"type":"object","$$ref":"#/components/schemas/NotificationEmail"},"thirdParty":{"description":"Third party notifications.","items":{"description":"Webhook notification.","properties":{"integrationId":{"description":"Integration ID.","example":"sl-101","type":"string"},"integrationType":{"description":"Integration type.","enum":["pager-duty","slack","app-dynamics","service-now"],"example":"slack","type":"string","$$ref":"#/components/schemas/ThirdPartyIntegrationType"}},"type":"object","$$ref":"#/components/schemas/NotificationThirdParty"},"type":"array"},"webhook":{"description":"Webhook notifications.","items":{"description":"Webhook notification.","properties":{"integrationId":{"description":"Integration ID.","example":"wb-201","type":"string"},"integrationType":{"description":"Integration type.","enum":["webhook"],"example":"webhook","type":"string","$$ref":"#/components/schemas/WebhookIntegrationType"}},"type":"object","$$ref":"#/components/schemas/NotificationWebhook"},"type":"array"},"customWebhook":{"description":"Custom webhook notifications.","items":{"description":"Custom webhook notification.","properties":{"integrationId":{"description":"Integration ID.","example":"6e069ae9-8537-4120-b988-61bf8e0d8b87","format":"uuid","type":"string"},"integrationType":{"description":"Integration type.","enum":["custom-webhook"],"example":"custom-webhook","type":"string","$$ref":"#/components/schemas/CustomWebhookIntegrationType"},"integrationName":{"description":"User-configured name of the integration.","example":"My webhook","type":"string"},"target":{"description":"Webhook target URL.","example":"https://example.com/test/webhooks/notifications","type":"string"}},"type":"object","$$ref":"#/components/schemas/NotificationCustomWebhook"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/AlertNotification"},"testIds":{"description":"Array of test IDs to link to alert rule (get `testId` from `/tests` endpoint).","example":["281474976710706","271659"],"items":{"type":"string"},"type":"array","$$ref":"#/components/schemas/RuleTestIds"}},"required":["alertType","expression","roundsViolatingOutOf","roundsViolatingRequired","ruleName"],"type":"object","$$ref":"#/components/schemas/RuleDetailUpdate"}}},"required":true},"responses":{"201":{"content":{"application/hal+json":{"schema":{"properties":{"ruleId":{"description":"Unique ID of the rule.","example":"127094","readOnly":true,"type":"string"},"ruleName":{"description":"Name of the alert rule.","example":"The End of the Internet","type":"string"},"expression":{"description":"The expression of the alert rule.","example":"((hops((hopDelay \u003e= 100 ms))))","type":"string"},"direction":{"description":"Direction for applicable alert types (eg. path trace, End-to-End (Agent) etc.)","enum":["to-target","from-target","bidirectional"],"example":"to-target","type":"string","$$ref":"#/components/schemas/AlertDirection"},"notifyOnClear":{"description":"Send notification when alert clears.","example":true,"type":"boolean"},"isDefault":{"description":"If set to `true`, this alert rule becomes the default for its test type and is automatically applied to newly created tests with relevant metrics. Only one default alert rule is allowed per test type.","example":true,"type":"boolean"},"alertType":{"description":"Type of alert being triggered. In multi-layered tests, this value represents the layer the alert relates to. See [Alert Details](https://developer.cisco.com/docs/thousandeyes/retrieve-alert-details/) documentation for a list of possible values","enum":["page-load","http-server","end-to-end-server","end-to-end-agent","voice","dns-server","dns-trace","dnssec","bgp","path-trace","ftp","sip-server","transactions","web-transactions","agent","network-outage","application-outage","device-device","device-interface","endpoint-network-server","endpoint-http-server","endpoint-path-trace","endpoint-browser-sessions-agent","endpoint-browser-sessions-application","api","web-transaction","unknown"],"example":"http-server","type":"string","$$ref":"#/components/schemas/AlertType"},"alertGroupType":{"description":"Category of alert type based on the application or network layer and source of the test.","enum":["bgp","browser-session","cloud-enterprise","endpoint"],"example":"endpoint","type":"string","$$ref":"#/components/schemas/AlertGroupType"},"minimumSources":{"description":"The minimum number of agents or monitors that must meet the specified criteria to trigger the alert.","example":10,"type":"integer"},"minimumSourcesPct":{"description":"The minimum percentage of all assigned agents or monitors that must meet the specified criteria to trigger the alert.","example":99,"type":"integer"},"roundsViolatingMode":{"description":"`exact` requires the same agents to meet the threshold in consecutive rounds. `auto` is only enabled for CEA and Endpoint Scheduled test rules. The default is `any`.","enum":["exact","any","auto"],"example":"exact","readOnly":true,"type":"string","$$ref":"#/components/schemas/AlertRoundsViolationMode"},"roundsViolatingOutOf":{"description":"Specifies the divisor (y value) in the “X of Y times” condition.","example":5,"type":"integer"},"roundsViolatingRequired":{"description":"Specifies the numerator (x value) in the “X of Y times” condition.","example":2,"type":"integer"},"includeCoveredPrefixes":{"description":"Set true to include covered prefixes in the BGP alert rule. Only applicable to BGP alert rules.","example":true,"type":"boolean"},"sensitivityLevel":{"description":"Used when `roundsViolatingMode` is set to `auto`. The default is `medium`. Higher sensitivity increases the likelihood of triggering alerts.","enum":["high","medium","low"],"example":"medium","readOnly":true,"type":"string","$$ref":"#/components/schemas/SensitivityLevel"},"severity":{"description":"The severity of the alert.","enum":["info","major","minor","critical","unknown"],"example":"major","type":"string","$$ref":"#/components/schemas/Severity"},"notifications":{"description":"Alert notification object. See Alert notification integrations.","properties":{"email":{"description":"Email notifications.","properties":{"recipients":{"description":"An array containing the email addresses to receive notifications.","example":["noreply@thousandeyes.com"],"items":{"type":"string"},"type":"array"},"message":{"description":"Custom text included in alert email notifications sent to recipients.","example":"Notification message","type":"string"}},"type":"object","$$ref":"#/components/schemas/NotificationEmail"},"thirdParty":{"description":"Third party notifications.","items":{"description":"Webhook notification.","properties":{"integrationId":{"description":"Integration ID.","example":"sl-101","type":"string"},"integrationType":{"description":"Integration type.","enum":["pager-duty","slack","app-dynamics","service-now"],"example":"slack","type":"string","$$ref":"#/components/schemas/ThirdPartyIntegrationType"}},"type":"object","$$ref":"#/components/schemas/NotificationThirdParty"},"type":"array"},"webhook":{"description":"Webhook notifications.","items":{"description":"Webhook notification.","properties":{"integrationId":{"description":"Integration ID.","example":"wb-201","type":"string"},"integrationType":{"description":"Integration type.","enum":["webhook"],"example":"webhook","type":"string","$$ref":"#/components/schemas/WebhookIntegrationType"}},"type":"object","$$ref":"#/components/schemas/NotificationWebhook"},"type":"array"},"customWebhook":{"description":"Custom webhook notifications.","items":{"description":"Custom webhook notification.","properties":{"integrationId":{"description":"Integration ID.","example":"6e069ae9-8537-4120-b988-61bf8e0d8b87","format":"uuid","type":"string"},"integrationType":{"description":"Integration type.","enum":["custom-webhook"],"example":"custom-webhook","type":"string","$$ref":"#/components/schemas/CustomWebhookIntegrationType"},"integrationName":{"description":"User-configured name of the integration.","example":"My webhook","type":"string"},"target":{"description":"Webhook target URL.","example":"https://example.com/test/webhooks/notifications","type":"string"}},"type":"object","$$ref":"#/components/schemas/NotificationCustomWebhook"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/AlertNotification"},"testIds":{"description":"Array of test IDs to link to alert rule (get `testId` from `/tests` endpoint).","example":["281474976710706","271659"],"items":{"type":"string"},"type":"array","$$ref":"#/components/schemas/RuleTestIds"},"_links":{"description":"A links object containing the self link.","properties":{"self":{"description":"A hyperlink from the containing resource to a URI.","properties":{"href":{"description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id","type":"string"},"templated":{"description":"Should be true when the link object's \"href\" property is a URI template.","type":"boolean"},"type":{"description":"Used as a hint to indicate the media type expected when dereferencing the target resource.","type":"string"},"deprecation":{"description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation.","type":"string"},"name":{"description":"Its value may be used as a secondary key for selecting link objects that share the same relation type.","type":"string"},"profile":{"description":"A URI that hints about the profile of the target resource.","type":"string"},"title":{"description":"Intended for labelling the link with a human-readable identifier","type":"string"},"hreflang":{"description":"Indicates the language of the target resource","type":"string"}},"required":["href"],"type":"object","$$ref":"#/components/schemas/Link"}},"readOnly":true,"type":"object","$$ref":"#/components/schemas/SelfLinks"}},"required":["alertType","expression","roundsViolatingOutOf","roundsViolatingRequired","ruleName"],"type":"object","$$ref":"#/components/schemas/Rule"}}},"description":"Created","headers":{"Location":{"description":"The absolute path to created resource.","schema":{"example":"https://api.thousandeyes.com/v7/link/to/resource/id","format":"uri","type":"string"},"$$ref":"#/components/headers/Location"}}},"400":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"Request validation failed. There are invalid or missing fields","status":400,"detail":"Your request object contains invalid fields.","instance":"/v7","errors":[{"code":"AM-5432","field":"firstName","message":"firstName cannot have fancy characters"},{"code":"DASH-5622","field":"password","message":"Password cannot be blank"}]},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"},"errors":{"description":"(Optional) When multiple errors occur, the details for each error are listed.","items":{"properties":{"code":{"description":"(Optional) A unique error type/code that can be referenced in the documentation for further details.","type":"string"},"field":{"description":"Identifies the field that triggered this particular error.","type":"string"},"message":{"description":"A short, human-readable summary of the error.","type":"string"}},"type":"object","$$ref":"#/components/schemas/ValidationErrorItem"},"nullable":true,"type":"array"}},"type":"object","$$ref":"#/components/schemas/ValidationError"}}},"description":"Bad Request"},"401":{"content":{"application/problem+json":{"schema":{"properties":{"error":{"example":"invalid_token","type":"string"},"error_description":{"example":"Invalid access token","type":"string"}},"type":"object","$$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Unauthorized"},"403":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Insufficient permissions to query endpoint"},"404":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"URI Resource Not Found","status":404,"detail":"Details explaining if the 404 error is related to an invalid URI or a wrong ID","instance":"/v7"},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Exhausted rate limit for the organization"},"500":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"Internal server error","status":500,"detail":"Optional detail about the internal error message.","instance":"/v7"},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Internal server error"}},"summary":"Create alert rule","tags":["Alert Rules"],"__originalOperationId":"createAlertRule","security":[{"BearerAuth":[]}],"method":"post","path":"/alerts/rules"}}