DigitalOcean API (unofficial showcase)
POST/v2/load_balancers

Create a load balancer

Creates a load balancer in the specified region and assigns Droplets to it. Provide either droplet_ids to select Droplets individually or tag to select Droplets by tag; these methods are mutually exclusive. A 202 response confirms acceptance and returns the load balancer object.

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

30 body fields

Load balancer configuration. Provide region and either droplet_ids or tag to choose how Droplets are assigned.

droplet_idsarray<integer>required
An array containing the IDs of the Droplets assigned to the load balancer.
ipstringoptional
An optional IP address to assign to the load balancer from one of your Bring Your Own IP (BYOIP) prefixes. The address must be an unassigned BYOIP address on your account in the same region as the load balancer. If omitted, DigitalOcean assigns a public IP address automatically. This field is only applied when creating the load balancer, cannot be changed afterward, and is not supported for `GLOBAL` or `INTERNAL` load balancers.
regionstringrequired
The slug identifier for the region where the resource will initially be available.
Allowed:ams1ams2ams3blr1fra1lon1nyc1nyc2nyc3sfo1sfo2sfo3
idstringoptional
A unique ID that can be used to identify and reference a load balancer.
namestringoptional
A human-readable name for a load balancer instance.
project_idstringoptional
The ID of the project that the load balancer is associated with. If no ID is provided at creation, the load balancer associates with the user's default project. If an invalid project ID is provided, the load balancer will not be created.
ipv6stringoptional
An attribute containing the public-facing IPv6 address of the load balancer.
size_unitintegeroptional
How many nodes the load balancer contains. Each additional node increases the load balancer's ability to manage more connections. Load balancers can be scaled up or down, and you can change the number of nodes after creation up to once per hour. This field is currently not available in the AMS2, NYC2, or SFO1 regions. Use the `size` field to scale load balancers that reside in these regions.
Default:1
sizestringdeprecatedoptional
This field has been replaced by the `size_unit` field for all regions except in AMS2, NYC2, and SFO1. Each available load balancer size now equates to the load balancer having a set number of nodes. * `lb-small` = 1 node * `lb-medium` = 3 nodes * `lb-large` = 6 nodes You can resize load balancers after creation up to once per hour. You cannot resize a load balancer within the first hour of its creation.
Allowed:lb-smalllb-mediumlb-largeDefault:lb-small
algorithmstringdeprecatedoptional
This field has been deprecated. You can no longer specify an algorithm for load balancers.
Allowed:round_robinleast_connectionsDefault:round_robin
statusstringoptional
A status string indicating the current state of the load balancer. This can be `new`, `active`, or `errored`.
Allowed:newactiveerrored
created_atstringoptional
A time value given in ISO8601 combined date and time format that represents when the load balancer was created.
forwarding_rulesarray<object>required
An array of objects specifying the forwarding rules for a load balancer.
health_checkobjectoptional
An object specifying health check settings for the load balancer.
sticky_sessionsobjectoptional
An object specifying sticky sessions settings for the load balancer.
redirect_http_to_httpsbooleanoptional
A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.
Default:false
enable_proxy_protocolbooleanoptional
A boolean value indicating whether PROXY Protocol is in use.
Default:false
enable_backend_keepalivebooleanoptional
A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.
Default:false
http_idle_timeout_secondsintegeroptional
An integer value which configures the idle timeout for HTTP requests to the target droplets.
Default:60
vpc_uuidstringoptional
A string specifying the UUID of the VPC to which the load balancer is assigned.
subnet_uuidstringoptional
A string specifying the UUID of the VPC subnet to which the load balancer is assigned.
disable_lets_encrypt_dns_recordsbooleanoptional
A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.
Default:false
firewallobjectoptional
An object specifying allow and deny rules to control traffic to the load balancer.
networkstringoptional
A string indicating whether the load balancer should be external or internal. Internal load balancers have no public IPs and are only accessible to resources on the same VPC network. This property cannot be updated after creating the load balancer.
Allowed:EXTERNALINTERNALDefault:EXTERNAL
network_stackstringoptional
A string indicating whether the load balancer will support IPv4 or both IPv4 and IPv6 networking. This property cannot be updated after creating the load balancer.
Allowed:IPV4DUALSTACKDefault:IPV4
typestringoptional
A string indicating whether the load balancer should be a standard regional HTTP load balancer, a regional network load balancer that routes traffic at the TCP/UDP transport layer, or a global load balancer.
Allowed:REGIONALREGIONAL_NETWORKGLOBALDefault:REGIONAL
domainsarray<object>optional
An array of objects specifying the domain configurations for a Global load balancer.
glb_settingsobjectoptional
An object specifying forwarding configurations for a Global load balancer.
target_load_balancer_idsarray<string>optional
An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.
tls_cipher_policystringoptional
A string indicating the policy for the TLS cipher suites used by the load balancer. The possible values are `DEFAULT` or `STRONG`. The default value is `DEFAULT`.
Allowed:DEFAULTSTRONGDefault:DEFAULT

5 status codes
202Returns an accepted response containing a `load_balancer` object.
load_balancerobjectoptional
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 indicates invalid authentication credentials. A 429 indicates the API rate limit has been exceeded, and a 500 indicates a server error. Provide region and exactly one of droplet_ids or tag; the two assignment methods are mutually exclusive.