DigitalOcean API (unofficial showcase)
POST/v2/monitoring/alerts

Create an alert policy

Creates an alert policy that monitors a selected metric for droplets, load balancers, databases, or autoscale pools. Set type, entities, and tags to define what the policy monitors; when both entities and tags are empty, it applies to all entities of the selected type in the account. A 200 response returns the alert policy, including its generated UUID.

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

9 body fields

Alert policy configuration. Include all required fields: type, description, compare, value, window, entities, tags, alerts, and enabled.

alertsobjectrequired
Notification destinations for the policy, including `slack` integrations and `email` addresses. Both fields are required; each Slack integration requires a `url` and `channel`.
comparestringrequired
Comparison used to evaluate the alert threshold: `GreaterThan` or `LessThan`.
Allowed:GreaterThanLessThan
descriptionstringrequired
A description of the alert policy.
enabledbooleanrequired
Whether the alert policy is enabled.
entitiesarray<string>required
Identifiers of the entities to monitor; use identifiers that match the entity type selected by `type`.
tagsarray<string>required
Tags used to select entities to monitor. If both `tags` and `entities` are empty, the policy applies to all account entities of the selected type.
typestringrequired
Metric or event type that the policy monitors, such as `v1/insights/droplet/cpu` or `v1/droplet/autoscale_alerts/scale_up`; supported types determine the valid entity identifiers.
Allowed:v1/insights/droplet/load_1v1/insights/droplet/load_5v1/insights/droplet/load_15v1/insights/droplet/memory_utilization_percentv1/insights/droplet/disk_utilization_percentv1/insights/droplet/cpuv1/insights/droplet/disk_readv1/insights/droplet/disk_writev1/insights/droplet/public_outbound_bandwidthv1/insights/droplet/public_inbound_bandwidthv1/insights/droplet/private_outbound_bandwidthv1/insights/droplet/private_inbound_bandwidth
valuenumberrequired
Numeric threshold for the selected metric.
windowstringrequired
Evaluation window: `5m`, `10m`, `30m`, or `1h`.
Allowed:5m10m30m1h

5 status codes
200Returns the alert policy, including its UUID, metric type, description, threshold, evaluation window, monitored entities and tags, notification settings, and enabled state.
policyobjectoptional
401Returned when authentication 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.
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.
defaultThere was an unexpected error.
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 401 is returned when authentication credentials are invalid, a 429 when the API rate limit is exceeded, and a 500 when a server error occurs. The body requires type, description, compare, value, window, entities, tags, alerts, and enabled; compare must be GreaterThan or LessThan, and window must be 5m, 10m, 30m, or 1h. Include both slack and email in alerts, and ensure each Slack integration includes url and channel.