DigitalOcean API (unofficial showcase)
POST/v2/firewalls

Create a firewall

Creates a firewall with access rules for controlling traffic to and from attached resources. Provide name and at least one of inbound_rules or outbound_rules in the request body. A 202 response returns the firewall object and its standard attributes.

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

9 body fields

Firewall configuration, including a name and at least one inbound or outbound access rule.

idstringoptional
A unique ID that can be used to identify and reference a firewall.
statusstringoptional
A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".
Allowed:waitingsucceededfailed
created_atstringoptional
A time value given in ISO8601 combined date and time format that represents when the firewall was created.
pending_changesarray<object>optional
An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.
namestringrequired
A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).
droplet_idsarray<integer>optional
An array containing the IDs of the Droplets assigned to the firewall. <br><br>Requires `droplet:read` scope.
tagsobjectoptional
The tags used to associate resources with the firewall, if supplied.
inbound_rulesarray<object>optional
Inbound access rules for the firewall. Include this field or `outbound_rules`.
outbound_rulesarray<object>optional
Outbound access rules for the firewall. Include this field or `inbound_rules`.

6 status codes
202Returns a firewall object containing the standard firewall attributes.
firewallobjectoptional
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.
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

The request body must include name and at least one of inbound_rules or outbound_rules; a body parsing error returns a 400. Invalid credentials return a 401, exceeding the rate limit returns a 429, and a server error returns a 500.