DigitalOcean API (unofficial showcase)
POST/v2/insights/alert-rules

Create an alert rule

Creates an alert rule for a metric query and its configured thresholds. Provide a spec with name, query, thresholds, and at least one notification_channels binding; status defaults to ALERT_RULE_STATUS_ACTIVE and re_alert_duration defaults to RE_ALERT_DURATION_4H when omitted. Use a dotted OpenTelemetry metric name for query.metric, such as do.droplets.cpu_utilization.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 body fields

Alert rule creation details. spec is required and must include name, query, thresholds, and at least one notification_channels binding.

specobjectrequired
The alert rule configuration, including its name, query, thresholds, optional condition and re-alert duration, and at least one notification channel binding.
statusstringoptional
Desired alert rule status. Allowed values: - `ALERT_RULE_STATUS_ACTIVE` = active - `ALERT_RULE_STATUS_PAUSED` = paused
Allowed:ALERT_RULE_STATUS_ACTIVEALERT_RULE_STATUS_PAUSED

7 status codes
201Returns the created alert rule, including its identifier, specification, status, and creation and update timestamps.
alert_ruleobjectrequired
An Insights alert rule.
400Returned when the request body cannot be parsed.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
422Returned when the request is unprocessable, including when `query.metric` uses an underscored Prometheus-style name instead of a dotted OpenTelemetry name.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultReturned when an unexpected error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned when the request body cannot be parsed, a 401 when authentication fails, a 422 when query.metric uses an underscored Prometheus-style name, a 429 when the API rate limit is exceeded, and a 500 when a server error occurs. spec must include name, query, thresholds, and at least one notification_channels binding; status, if provided, must be ALERT_RULE_STATUS_ACTIVE or ALERT_RULE_STATUS_PAUSED.