Give Feedback

Load Balancers

Generated on 3 Apr 2026

Copy page as Markdown View page as Markdown

DigitalOcean Load Balancers provide a way to distribute traffic across multiple Droplets. By sending requests to the /v2/load_balancers endpoint, you can list, create, or delete load balancers as well as add or remove Droplets, forwarding rules, and other configuration details.

Base URL https://api.digitalocean.com

Endpoints

GET List All Load Balancers POST Create a New Load Balancer GET Retrieve an Existing Load Balancer PUT Update a Load Balancer DELETE Delete a Load Balancer DELETE Delete a Global Load Balancer CDN Cache POST Add Droplets to a Load Balancer DELETE Remove Droplets from a Load Balancer POST Add Forwarding Rules to a Load Balancer DELETE Remove Forwarding Rules from a Load Balancer

GET List All Load Balancers

/v2/load_balancers

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all of the load balancer instances on your account, send a GET request to /v2/load_balancers.

Query Parameters

per_page integer 1 – 200 optional

Example: 2

Number of items returned per page

Default: 20

page integer >= 1 optional

Example: 1

Which 'page' of paginated results to return.

Default: 1

Request: `/v2/load_balancers`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/load_balancers"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    opt := &godo.ListOptions{
        Page:    1,
        PerPage: 200,
    }

    lbs, _, err := c.LoadBalancers.List(ctx, opt)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

load_balancers = client.load_balancers.all
load_balancers.each

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.load_balancers.list()

Responses

200

A JSON object with a key of load_balancers. This will be set to an array of objects, each of which will contain the standard load balancer attributes.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

load_balancers array of object optional

Show child properties

algorithm string, one of: round_robin, least_connections optional Deprecated

Example: round_robin

This field has been deprecated. You can no longer specify an algorithm for load balancers.

created_at string (date-time) optional read-only

Example: 2017-02-01T22:22:58Z

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

disable_lets_encrypt_dns_records boolean optional

Example: true

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains array of object optional

An array of objects specifying the domain configurations for a Global load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination.

is_managed boolean optional

Example: true

A boolean value indicating if the domain is already managed by DigitalOcean. If true, all A and AAAA records required to enable Global load balancers will be automatically added.

name string optional

Example: example.com

FQDN to associate with a Global load balancer.

enable_backend_keepalive boolean optional

Example: true

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol boolean optional

Example: true

A boolean value indicating whether PROXY Protocol is in use.

firewall object optional

An object specifying allow and deny rules to control traffic to the load balancer.

Show child properties

allow array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for allowing traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

deny array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for denying traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

forwarding_rules array of object required

An array of objects specifying the forwarding rules for a load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

The protocol used for traffic to the load balancer. The possible values are: http, https, http2, http3, tcp, or udp. If you set the entry_protocol to udp, the target_protocol must be set to udp. When using UDP, the load balancer requires that you set up a health check with a port that uses TCP, HTTP, or HTTPS to work properly.

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

The protocol used for traffic from the load balancer to the backend Droplets. The possible values are: http, https, http2, tcp, or udp. If you set the target_protocol to udp, the entry_protocol must be set to udp. When using UDP, the load balancer requires that you set up a health check with a port that uses TCP, HTTP, or HTTPS to work properly.

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

glb_settings object optional

An object specifying forwarding configurations for a Global load balancer.

Show child properties

cdn object optional

An object specifying CDN configurations for a Global load balancer.

Show child properties

is_enabled boolean optional

Example: true

A boolean flag to enable CDN caching.

failover_threshold integer optional

Example: 50

An integer value as a percentage to indicate failure threshold to decide how the regional priorities will take effect. A value of 50 would indicate that the Global load balancer will choose a lower priority region to forward traffic to once this failure threshold has been reached for the higher priority region.

region_priorities object optional

Example: {"fra1":2,"nyc1":1,"sgp1":3}

A map of region string to an integer priority value indicating preference for which regional target a Global load balancer will forward traffic to. A lower value indicates a higher priority.

target_port integer optional

Example: 80

An integer representing the port on the target backends which the load balancer will forward traffic to.

target_protocol string, one of: http, https, http2 optional

Example: http

The protocol used for forwarding traffic from the load balancer to the target backends. The possible values are http, https and http2.

health_check object optional

An object specifying health check settings for the load balancer.

Show child properties

check_interval_seconds integer optional

Example: 10

The number of seconds between between two consecutive health checks.

healthy_threshold integer optional

Example: 3

The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool.

path string optional

Example: /

The path on the backend Droplets to which the load balancer instance will send a request.

port integer optional

Example: 80

An integer representing the port on the backend Droplets on which the health check will attempt a connection.

protocol string, one of: http, https, tcp optional

Example: http

The protocol used for health checks sent to the backend Droplets. The possible values are http, https, or tcp.

response_timeout_seconds integer optional

Example: 5

The number of seconds the load balancer instance will wait for a response until marking a health check as failed.

unhealthy_threshold integer optional

Example: 5

The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool.

http_idle_timeout_seconds integer optional

Example: 90

An integer value which configures the idle timeout for HTTP requests to the target droplets.

id string (uuid) optional read-only

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique ID that can be used to identify and reference a load balancer.

ip string optional read-only

Example: 104.131.186.241

An attribute containing the public-facing IP address of the load balancer.

ipv6 string optional read-only

Example: 2604:a880:800:14::85f5:c000

An attribute containing the public-facing IPv6 address of the load balancer.

name string optional

Example: example-lb-01

A human-readable name for a load balancer instance.

network string, one of: EXTERNAL, INTERNAL optional

Example: EXTERNAL

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.

network_stack string, one of: IPV4, DUALSTACK optional

Example: IPV4

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.

project_id string optional

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

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.

redirect_http_to_https boolean optional

Example: true

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

size string, one of: lb-small, lb-medium, lb-large optional Deprecated

Example: lb-small

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.

size_unit integer optional

Example: 3

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.

status string, one of: new, active, errored optional read-only

Example: new

A status string indicating the current state of the load balancer. This can be new, active, or errored.

sticky_sessions object optional

An object specifying sticky sessions settings for the load balancer.

Show child properties

cookie_name string optional

Example: DO-LB

The name of the cookie sent to the client. This attribute is only returned when using cookies for the sticky sessions type.

cookie_ttl_seconds integer optional

Example: 300

The number of seconds until the cookie set by the load balancer expires. This attribute is only returned when using cookies for the sticky sessions type.

type string, one of: cookies, none optional

Example: cookies

An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are cookies or none.

target_load_balancer_ids array of string optional

Example: ["7dbf91fe-cbdb-48dc-8290-c3a181554905","996fa239-fac3-42a2-b9a1-9fa822268b7a"]

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy string, one of: DEFAULT, STRONG optional

Example: STRONG

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.

type string, one of: REGIONAL, REGIONAL_NETWORK, GLOBAL optional

Example: REGIONAL

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.

vpc_uuid string (uuid) optional

Example: c33931f2-a26a-4e61-b85c-4e95a2ec431b

A string specifying the UUID of the VPC to which the load balancer is assigned.

region object optional

Show child properties

available boolean required

Example: true

This is a boolean value that represents whether new Droplets can be created in this region.

features array of string required

Example: ["private_networking","backups","ipv6","metadata","install_agent","storage","image_transfer"]

This attribute is set to an array which contains features available in this region

name string required

Example: New York 3

The display name of the region. This will be a full name that is used in the control panel and other interfaces.

sizes array of string required

This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.

slug string required

Example: nyc3

A human-readable string that is used as a unique identifier for each region.

droplet_ids array of integer optional

Example: [3164444,3164445]

An array containing the IDs of the Droplets assigned to the load balancer.

tag string optional

Example: prod:web

The name of a Droplet tag corresponding to Droplets assigned to the load balancer.

links object optional

Show child properties

pages anyOf optional

One of:

Forward Links

last string optional

Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional

Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links

first string optional

Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional

Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "links": {},
  "load_balancers": [
    {
      "algorithm": "round_robin",
      "created_at": "2017-02-01T22:22:58Z",
      "disable_lets_encrypt_dns_records": false,
      "droplet_ids": [
        3164444,
        3164445
      ],
      "enable_backend_keepalive": false,
      "enable_proxy_protocol": false,
      "firewall": {
        "allow": [
          "ip:1.2.3.4",
          "cidr:2.3.4.0/24"
        ],
        "deny": [
          "cidr:1.2.0.0/16",
          "ip:2.3.4.5"
        ]
      },
      "forwarding_rules": [
        {
          "certificate_id": "",
          "entry_port": 80,
          "entry_protocol": "http",
          "target_port": 80,
          "target_protocol": "http",
          "tls_passthrough": false
        },
        {
          "certificate_id": "",
          "entry_port": 443,
          "entry_protocol": "https",
          "target_port": 443,
          "target_protocol": "https",
          "tls_passthrough": true
        }
      ],
      "health_check": {
        "check_interval_seconds": 10,
        "healthy_threshold": 5,
        "path": "/",
        "port": 80,
        "protocol": "http",
        "response_timeout_seconds": 5,
        "unhealthy_threshold": 3
      },
      "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
      "ip": "104.131.186.241",
      "name": "example-lb-01",
      "redirect_http_to_https": false,
      "region": {
        "available": true,
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent"
        ],
        "name": "New York 3",
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192gb"
        ],
        "slug": "nyc3"
      },
      "size": "lb-small",
      "status": "new",
      "sticky_sessions": {
        "type": "none"
      },
      "tag": "",
      "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
    },
    {
      "algorithm": "round_robin",
      "created_at": "2020-09-08T18:58:04Z",
      "disable_lets_encrypt_dns_records": false,
      "droplet_ids": [
        55806512,
        55806515,
        55806524
      ],
      "enable_backend_keepalive": false,
      "enable_proxy_protocol": false,
      "firewall": {
        "allow": [
          "ip:1.2.3.4",
          "cidr:2.3.4.0/24"
        ],
        "deny": [
          "cidr:1.2.0.0/16",
          "ip:2.3.4.5"
        ]
      },
      "forwarding_rules": [
        {
          "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
          "entry_port": 443,
          "entry_protocol": "https",
          "target_port": 8080,
          "target_protocol": "http",
          "tls_passthrough": false
        }
      ],
      "health_check": {
        "check_interval_seconds": 10,
        "healthy_threshold": 5,
        "path": "/",
        "port": 443,
        "protocol": "https",
        "response_timeout_seconds": 5,
        "unhealthy_threshold": 3
      },
      "http_idle_timeout_seconds": 60,
      "id": "56775c3f-04ab-4fb3-a7ed-40ef9bc8eece",
      "ip": "45.55.125.24",
      "name": "prod-web-lb-01",
      "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
      "redirect_http_to_https": true,
      "region": {
        "available": true,
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent"
        ],
        "name": "New York 3",
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192gb"
        ],
        "slug": "nyc3"
      },
      "size": "lb-small",
      "status": "active",
      "sticky_sessions": {
        "cookie_name": "DO-LB",
        "cookie_ttl_seconds": 300,
        "type": "cookies"
      },
      "tag": "prod:web",
      "vpc_uuid": "587d698c-de84-11e8-80bc-3cfdfea9fcd1"
    }
  ],
  "meta": {
    "total": 2
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Create a New Load Balancer

/v2/load_balancers

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a new load balancer instance, send a POST request to /v2/load_balancers.

You can specify the Droplets that will sit behind the load balancer using one of two methods:

Set droplet_ids to a list of specific Droplet IDs.
Set tag to the name of a tag. All Droplets with this tag applied will be assigned to the load balancer. Additional Droplets will be automatically assigned as they are tagged.

These methods are mutually exclusive.

Request Body: `application/json`

Assign Droplets by ID

droplet_ids array of integer optional

Example: [3164444,3164445]

An array containing the IDs of the Droplets assigned to the load balancer.

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource will initially be available.

algorithm string, one of: round_robin, least_connections optional Deprecated

Example: round_robin

This field has been deprecated. You can no longer specify an algorithm for load balancers.

created_at string (date-time) optional read-only

Example: 2017-02-01T22:22:58Z

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

disable_lets_encrypt_dns_records boolean optional

Example: true

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains array of object optional

An array of objects specifying the domain configurations for a Global load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination.

is_managed boolean optional

Example: true

A boolean value indicating if the domain is already managed by DigitalOcean. If true, all A and AAAA records required to enable Global load balancers will be automatically added.

name string optional

Example: example.com

FQDN to associate with a Global load balancer.

enable_backend_keepalive boolean optional

Example: true

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol boolean optional

Example: true

A boolean value indicating whether PROXY Protocol is in use.

firewall object optional

An object specifying allow and deny rules to control traffic to the load balancer.

Show child properties

allow array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for allowing traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

deny array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for denying traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

forwarding_rules array of object required

An array of objects specifying the forwarding rules for a load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

glb_settings object optional

An object specifying forwarding configurations for a Global load balancer.

Show child properties

cdn object optional

An object specifying CDN configurations for a Global load balancer.

Show child properties

is_enabled boolean optional

Example: true

A boolean flag to enable CDN caching.

failover_threshold integer optional

Example: 50

region_priorities object optional

Example: {"fra1":2,"nyc1":1,"sgp1":3}

A map of region string to an integer priority value indicating preference for which regional target a Global load balancer will forward traffic to. A lower value indicates a higher priority.

target_port integer optional

Example: 80

An integer representing the port on the target backends which the load balancer will forward traffic to.

target_protocol string, one of: http, https, http2 optional

Example: http

The protocol used for forwarding traffic from the load balancer to the target backends. The possible values are http, https and http2.

health_check object optional

An object specifying health check settings for the load balancer.

Show child properties

check_interval_seconds integer optional

Example: 10

The number of seconds between between two consecutive health checks.

healthy_threshold integer optional

Example: 3

The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool.

path string optional

Example: /

The path on the backend Droplets to which the load balancer instance will send a request.

port integer optional

Example: 80

An integer representing the port on the backend Droplets on which the health check will attempt a connection.

protocol string, one of: http, https, tcp optional

Example: http

The protocol used for health checks sent to the backend Droplets. The possible values are http, https, or tcp.

response_timeout_seconds integer optional

Example: 5

The number of seconds the load balancer instance will wait for a response until marking a health check as failed.

unhealthy_threshold integer optional

Example: 5

The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool.

http_idle_timeout_seconds integer optional

Example: 90

An integer value which configures the idle timeout for HTTP requests to the target droplets.

id string (uuid) optional read-only

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique ID that can be used to identify and reference a load balancer.

ip string optional read-only

Example: 104.131.186.241

An attribute containing the public-facing IP address of the load balancer.

ipv6 string optional read-only

Example: 2604:a880:800:14::85f5:c000

An attribute containing the public-facing IPv6 address of the load balancer.

name string optional

Example: example-lb-01

A human-readable name for a load balancer instance.

network string, one of: EXTERNAL, INTERNAL optional

Example: EXTERNAL

network_stack string, one of: IPV4, DUALSTACK optional

Example: IPV4

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.

project_id string optional

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

redirect_http_to_https boolean optional

Example: true

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

size string, one of: lb-small, lb-medium, lb-large optional Deprecated

Example: lb-small

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.

size_unit integer optional

Example: 3

status string, one of: new, active, errored optional read-only

Example: new

A status string indicating the current state of the load balancer. This can be new, active, or errored.

sticky_sessions object optional

An object specifying sticky sessions settings for the load balancer.

Show child properties

cookie_name string optional

Example: DO-LB

The name of the cookie sent to the client. This attribute is only returned when using cookies for the sticky sessions type.

cookie_ttl_seconds integer optional

Example: 300

The number of seconds until the cookie set by the load balancer expires. This attribute is only returned when using cookies for the sticky sessions type.

type string, one of: cookies, none optional

Example: cookies

An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are cookies or none.

target_load_balancer_ids array of string optional

Example: ["7dbf91fe-cbdb-48dc-8290-c3a181554905","996fa239-fac3-42a2-b9a1-9fa822268b7a"]

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy string, one of: DEFAULT, STRONG optional

Example: STRONG

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.

type string, one of: REGIONAL, REGIONAL_NETWORK, GLOBAL optional

Example: REGIONAL

vpc_uuid string (uuid) optional

Example: c33931f2-a26a-4e61-b85c-4e95a2ec431b

A string specifying the UUID of the VPC to which the load balancer is assigned.

Assign Droplets by Tag

tag string optional

Example: prod:web

The name of a Droplet tag corresponding to Droplets assigned to the load balancer.

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource will initially be available.

algorithm string, one of: round_robin, least_connections optional Deprecated

Example: round_robin

This field has been deprecated. You can no longer specify an algorithm for load balancers.

created_at string (date-time) optional read-only

Example: 2017-02-01T22:22:58Z

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

disable_lets_encrypt_dns_records boolean optional

Example: true

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains array of object optional

An array of objects specifying the domain configurations for a Global load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination.

is_managed boolean optional

Example: true

A boolean value indicating if the domain is already managed by DigitalOcean. If true, all A and AAAA records required to enable Global load balancers will be automatically added.

name string optional

Example: example.com

FQDN to associate with a Global load balancer.

enable_backend_keepalive boolean optional

Example: true

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol boolean optional

Example: true

A boolean value indicating whether PROXY Protocol is in use.

firewall object optional

An object specifying allow and deny rules to control traffic to the load balancer.

Show child properties

allow array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for allowing traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

deny array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for denying traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

forwarding_rules array of object required

An array of objects specifying the forwarding rules for a load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

glb_settings object optional

An object specifying forwarding configurations for a Global load balancer.

Show child properties

cdn object optional

An object specifying CDN configurations for a Global load balancer.

Show child properties

is_enabled boolean optional

Example: true

A boolean flag to enable CDN caching.

failover_threshold integer optional

Example: 50

region_priorities object optional

Example: {"fra1":2,"nyc1":1,"sgp1":3}

A map of region string to an integer priority value indicating preference for which regional target a Global load balancer will forward traffic to. A lower value indicates a higher priority.

target_port integer optional

Example: 80

An integer representing the port on the target backends which the load balancer will forward traffic to.

target_protocol string, one of: http, https, http2 optional

Example: http

The protocol used for forwarding traffic from the load balancer to the target backends. The possible values are http, https and http2.

health_check object optional

An object specifying health check settings for the load balancer.

Show child properties

check_interval_seconds integer optional

Example: 10

The number of seconds between between two consecutive health checks.

healthy_threshold integer optional

Example: 3

The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool.

path string optional

Example: /

The path on the backend Droplets to which the load balancer instance will send a request.

port integer optional

Example: 80

An integer representing the port on the backend Droplets on which the health check will attempt a connection.

protocol string, one of: http, https, tcp optional

Example: http

The protocol used for health checks sent to the backend Droplets. The possible values are http, https, or tcp.

response_timeout_seconds integer optional

Example: 5

The number of seconds the load balancer instance will wait for a response until marking a health check as failed.

unhealthy_threshold integer optional

Example: 5

The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool.

http_idle_timeout_seconds integer optional

Example: 90

An integer value which configures the idle timeout for HTTP requests to the target droplets.

id string (uuid) optional read-only

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique ID that can be used to identify and reference a load balancer.

ip string optional read-only

Example: 104.131.186.241

An attribute containing the public-facing IP address of the load balancer.

ipv6 string optional read-only

Example: 2604:a880:800:14::85f5:c000

An attribute containing the public-facing IPv6 address of the load balancer.

name string optional

Example: example-lb-01

A human-readable name for a load balancer instance.

network string, one of: EXTERNAL, INTERNAL optional

Example: EXTERNAL

network_stack string, one of: IPV4, DUALSTACK optional

Example: IPV4

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.

project_id string optional

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

redirect_http_to_https boolean optional

Example: true

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

size string, one of: lb-small, lb-medium, lb-large optional Deprecated

Example: lb-small

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.

size_unit integer optional

Example: 3

status string, one of: new, active, errored optional read-only

Example: new

A status string indicating the current state of the load balancer. This can be new, active, or errored.

sticky_sessions object optional

An object specifying sticky sessions settings for the load balancer.

Show child properties

cookie_name string optional

Example: DO-LB

The name of the cookie sent to the client. This attribute is only returned when using cookies for the sticky sessions type.

cookie_ttl_seconds integer optional

Example: 300

The number of seconds until the cookie set by the load balancer expires. This attribute is only returned when using cookies for the sticky sessions type.

type string, one of: cookies, none optional

Example: cookies

An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are cookies or none.

target_load_balancer_ids array of string optional

Example: ["7dbf91fe-cbdb-48dc-8290-c3a181554905","996fa239-fac3-42a2-b9a1-9fa822268b7a"]

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy string, one of: DEFAULT, STRONG optional

Example: STRONG

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.

type string, one of: REGIONAL, REGIONAL_NETWORK, GLOBAL optional

Example: REGIONAL

vpc_uuid string (uuid) optional

Example: c33931f2-a26a-4e61-b85c-4e95a2ec431b

A string specifying the UUID of the VPC to which the load balancer is assigned.

Request: `/v2/load_balancers`

Payload

Content type application/json

Example

{
  "forwarding_rules": [
    {
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 8080,
      "target_protocol": "http"
    }
  ],
  "name": "example-lb-01",
  "region": "nyc3",
  "tag": "prod:web"
}

{
  "droplet_ids": [
    3164444,
    3164445
  ],
  "firewall": {
    "allow": [
      "ip:1.2.3.4",
      "cidr:2.3.4.0/24"
    ],
    "deny": [
      "cidr:1.2.0.0/16",
      "ip:2.3.4.5"
    ]
  },
  "forwarding_rules": [
    {
      "entry_port": 80,
      "entry_protocol": "http",
      "target_port": 80,
      "target_protocol": "http"
    },
    {
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 443,
      "target_protocol": "https",
      "tls_passthrough": true
    }
  ],
  "http_idle_timeout_seconds": 60,
  "name": "example-lb-01",
  "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
  "region": "nyc3"
}

{
  "droplet_ids": [
    3164444,
    3164445
  ],
  "forwarding_rules": [
    {
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 8080,
      "target_protocol": "http"
    }
  ],
  "name": "example-lb-01",
  "region": "nyc3"
}

{
  "forwarding_rules": [
    {
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 8080,
      "target_protocol": "http"
    }
  ],
  "health_check": {
    "check_interval_seconds": 10,
    "healthy_threshold": 5,
    "path": "/health",
    "port": 8080,
    "protocol": "http",
    "response_timeout_seconds": 5,
    "unhealthy_threshold": 3
  },
  "name": "example-lb-01",
  "region": "nyc3",
  "sticky_sessions": {
    "cookie_name": "LB_COOKIE",
    "cookie_ttl_seconds": 300,
    "type": "cookies"
  },
  "tag": "prod:web"
}

cURL

# Create new load balancer
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name": "example-lb-01","size_unit": 1, "region": "nyc3", "forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80,"certificate_id":"","tls_passthrough":false}, {"entry_protocol": "https","entry_port": 444,"target_protocol": "https","target_port": 443,"tls_passthrough": true}], "health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3}, "sticky_sessions":{"type":"none"}, "firewall":{"deny":["ip:1.2.3.4","cidr:2.3.4.0/24"],"allow":["cidr:1.2.0.0/16","ip:2.3.4.5"]}, "droplet_ids": [3164444, 3164445]}' \
  "https://api.digitalocean.com/v2/load_balancers"

# Create new load balancer with Droplet tag
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name": "example-lb-01", "region": "nyc3", "size_unit": 1, "forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80,"certificate_id":"","tls_passthrough":false}, {"entry_protocol": "https","entry_port": 444,"target_protocol": "https","target_port": 443,"tls_passthrough": true}], "health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3}, "sticky_sessions":{"type":"none"}, "firewall":{"deny":["ip:1.2.3.4", "cidr:2.3.4.0/24"],"allow":["cidr:1.2.0.0/16","ip:2.3.4.5"]}, "tag": "web:prod"}' \
  "https://api.digitalocean.com/v2/load_balancers"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    createRequest := &godo.LoadBalancerRequest{
        Name:      "example-01",
        SizeUnit: "1",
        Algorithm: "round_robin",
        Region:    "nyc3",
        ForwardingRules: []godo.ForwardingRule{
            {
                EntryProtocol:  "http",
                EntryPort:      80,
                TargetProtocol: "http",
                TargetPort:     80,
            },
            {
                EntryProtocol:  "https",
                EntryPort:      443,
                TargetProtocol: "https",
                TargetPort:     443,
                TlsPassthrough: true,
            },
        },
        HealthCheck: &godo.HealthCheck{
            Protocol:               "http",
            Port:                   80,
            Path:                   "/",
            CheckIntervalSeconds:   10,
            ResponseTimeoutSeconds: 5,
            HealthyThreshold:       5,
            UnhealthyThreshold:     3,
        },
        StickySessions: &godo.StickySessions{
            Type: "none",
        },
        DropletIDs:          []int{3164444, 3164445},
        RedirectHttpToHttps: false,
        Firewall:            &godo.LBFirewall{
            Deny: []string{"ip:1.2.3.4", "cidr:2.3.4.0/24"},
            Allow: []string{"cidr:1.2.0.0/16", "ip:2.3.4.5"},
        }
  // Create new load balancer with Droplet tag
  //     Tag:                 "web:prod",
  //     RedirectHttpToHttps: false,
    }

    lb, _, err := client.LoadBalancers.Create(ctx, createRequest)

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

load_balancer = DropletKit::LoadBalancer.new(
  name: 'example-lb-01',
  size_unit: '1',
  algorithm: 'round_robin',
# Create new load balancer with Droplet tag
# tag: 'web:prod',
  droplet_ids: [ 3164444, 3164445],
  redirect_http_to_https: true,
  region: 'nyc3',
  forwarding_rules: [
    DropletKit::ForwardingRule.new(
      entry_protocol: 'http',
      entry_port: 80,
      target_protocol: 'http',
      target_port: 80,
      certificate_id: '',
      tls_passthrough: false
    ),
    DropletKit::ForwardingRule.new(
      entry_protocol: 'https',
      entry_port: 443,
      target_protocol: 'https',
      target_port: 443,
      certificate_id: '',
      tls_passthrough: true
    )
  ],
  sticky_sessions: DropletKit::StickySession.new(
    type: 'cookies',
    cookie_name: 'DO-LB',
    cookie_ttl_seconds: 5
  ),
  health_check: DropletKit::HealthCheck.new(
    protocol: 'http',
    port: 80,
    path: '/',
    check_interval_seconds: 10,
    response_timeout_seconds: 5,
    healthy_threshold: 5,
    unhealthy_threshold: 3
  )
)
client.load_balancers.create(load_balancer)

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "example-lb-01",
  "region": "nyc3",
  "forwarding_rules": [
    {
      "entry_protocol": "http",
      "entry_port": 80,
      "target_protocol": "http",
      "target_port": 80
    },
    {
      "entry_protocol": "https",
      "entry_port": 443,
      "target_protocol": "https",
      "target_port": 443,
      "tls_passthrough": True
    }
  ],
  "droplet_ids": [
    3164444,
    3164445
  ],
  "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
  "http_idle_timeout_seconds": 60,
  "firewall": {
    "deny": [
      "cidr:1.2.0.0/16",
      "ip:2.3.4.5"
    ],
    "allow": [
      "ip:1.2.3.4",
      "cidr:2.3.4.0/24"
    ]
  }
}

resp = client.load_balancers.create(body=req)

Responses

202

Accepted

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

load_balancer object optional

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

202

Example

{
  "load_balancer": {
    "algorithm": "round_robin",
    "created_at": "2017-02-01T22:22:58Z",
    "disable_lets_encrypt_dns_records": false,
    "droplet_ids": [
      3164444,
      3164445
    ],
    "enable_backend_keepalive": false,
    "enable_proxy_protocol": false,
    "firewall": {
      "allow": [
        "ip:1.2.3.4",
        "cidr:2.3.4.0/24"
      ],
      "deny": [
        "cidr:1.2.0.0/16",
        "ip:2.3.4.5"
      ]
    },
    "forwarding_rules": [
      {
        "certificate_id": "",
        "entry_port": 80,
        "entry_protocol": "http",
        "target_port": 80,
        "target_protocol": "http",
        "tls_passthrough": false
      },
      {
        "certificate_id": "",
        "entry_port": 443,
        "entry_protocol": "https",
        "target_port": 443,
        "target_protocol": "https",
        "tls_passthrough": true
      }
    ],
    "health_check": {
      "check_interval_seconds": 10,
      "healthy_threshold": 5,
      "path": "/",
      "port": 80,
      "protocol": "http",
      "response_timeout_seconds": 5,
      "unhealthy_threshold": 3
    },
    "http_idle_timeout_seconds": 60,
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "ip": "104.131.186.241",
    "name": "example-lb-01",
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "redirect_http_to_https": false,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "slug": "nyc3"
    },
    "size": "lb-small",
    "status": "new",
    "sticky_sessions": {
      "type": "none"
    },
    "tag": "",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
  }
}

{
  "load_balancer": {
    "algorithm": "round_robin",
    "created_at": "2017-02-01T22:22:58Z",
    "disable_lets_encrypt_dns_records": false,
    "droplet_ids": [
      3164444,
      3164445
    ],
    "enable_backend_keepalive": false,
    "enable_proxy_protocol": false,
    "forwarding_rules": [
      {
        "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
        "entry_port": 443,
        "entry_protocol": "https",
        "target_port": 8080,
        "target_protocol": "http"
      }
    ],
    "health_check": {
      "check_interval_seconds": 10,
      "healthy_threshold": 5,
      "path": "/",
      "port": 80,
      "protocol": "http",
      "response_timeout_seconds": 5,
      "unhealthy_threshold": 3
    },
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "ip": "104.131.186.241",
    "name": "example-lb-01",
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "redirect_http_to_https": false,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "slug": "nyc3"
    },
    "size": "lb-small",
    "status": "new",
    "sticky_sessions": {
      "type": "none"
    },
    "tag": "prod:web",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
  }
}

{
  "load_balancer": {
    "algorithm": "round_robin",
    "created_at": "2017-02-01T22:22:58Z",
    "disable_lets_encrypt_dns_records": false,
    "droplet_ids": [
      3164444,
      3164445
    ],
    "enable_backend_keepalive": false,
    "enable_proxy_protocol": false,
    "forwarding_rules": [
      {
        "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
        "entry_port": 443,
        "entry_protocol": "https",
        "target_port": 8080,
        "target_protocol": "http"
      }
    ],
    "health_check": {
      "check_interval_seconds": 10,
      "healthy_threshold": 5,
      "path": "/",
      "port": 80,
      "protocol": "http",
      "response_timeout_seconds": 5,
      "unhealthy_threshold": 3
    },
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "ip": "104.131.186.241",
    "name": "example-lb-01",
    "redirect_http_to_https": false,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "slug": "nyc3"
    },
    "size": "lb-small",
    "status": "new",
    "sticky_sessions": {
      "type": "none"
    },
    "tag": "",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
  }
}

{
  "load_balancer": {
    "algorithm": "round_robin",
    "created_at": "2017-02-01T22:22:58Z",
    "disable_lets_encrypt_dns_records": false,
    "droplet_ids": [
      3164444,
      3164445
    ],
    "enable_backend_keepalive": false,
    "enable_proxy_protocol": false,
    "forwarding_rules": [
      {
        "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
        "entry_port": 443,
        "entry_protocol": "https",
        "target_port": 8080,
        "target_protocol": "http"
      }
    ],
    "health_check": {
      "check_interval_seconds": 10,
      "healthy_threshold": 5,
      "path": "/health",
      "port": 8080,
      "protocol": "http",
      "response_timeout_seconds": 5,
      "unhealthy_threshold": 3
    },
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "ip": "104.131.186.241",
    "name": "example-lb-01",
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "redirect_http_to_https": false,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "slug": "nyc3"
    },
    "size": "lb-small",
    "status": "new",
    "sticky_sessions": {
      "cookie_name": "LB_COOKIE",
      "cookie_ttl_seconds": 300,
      "type": "cookies"
    },
    "tag": "prod:web",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Load Balancer

/v2/load_balancers/{lb_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To show information about a load balancer instance, send a GET request to /v2/load_balancers/$LOAD_BALANCER_ID.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request: `/v2/load_balancers/{lb_id}`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    lb, _, err := client.LoadBalancers.Get(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6")
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.load_balancers.find(id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.load_balancers.get(lb_id="afda3ad")

Responses

200

The response will be a JSON object with a key called load_balancer. The value of this will be an object that contains the standard attributes associated with a load balancer

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

load_balancer object optional

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "load_balancer": {
    "algorithm": "round_robin",
    "created_at": "2017-02-01T22:22:58Z",
    "disable_lets_encrypt_dns_records": false,
    "droplet_ids": [
      3164444,
      3164445
    ],
    "enable_backend_keepalive": false,
    "enable_proxy_protocol": false,
    "firewall": {
      "allow": [
        "ip:1.2.3.4",
        "cidr:2.3.4.0/24"
      ],
      "deny": [
        "cidr:1.2.0.0/16",
        "ip:2.3.4.5"
      ]
    },
    "forwarding_rules": [
      {
        "certificate_id": "",
        "entry_port": 80,
        "entry_protocol": "http",
        "target_port": 80,
        "target_protocol": "http",
        "tls_passthrough": false
      },
      {
        "certificate_id": "",
        "entry_port": 443,
        "entry_protocol": "https",
        "target_port": 443,
        "target_protocol": "https",
        "tls_passthrough": true
      }
    ],
    "health_check": {
      "check_interval_seconds": 10,
      "healthy_threshold": 5,
      "path": "/",
      "port": 80,
      "protocol": "http",
      "response_timeout_seconds": 5,
      "unhealthy_threshold": 3
    },
    "http_idle_timeout_seconds": 60,
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "ip": "104.131.186.241",
    "name": "example-lb-01",
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "redirect_http_to_https": false,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "slug": "nyc3"
    },
    "size": "lb-small",
    "status": "new",
    "sticky_sessions": {
      "type": "none"
    },
    "tag": "",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

PUT Update a Load Balancer

/v2/load_balancers/{lb_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update a load balancer's settings, send a PUT request to /v2/load_balancers/$LOAD_BALANCER_ID. The request should contain a full representation of the load balancer including existing attributes. It may contain one of the droplets_ids or tag attributes as they are mutually exclusive. Note that any attribute that is not provided will be reset to its default value.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request Body: `application/json`

Assign Droplets by ID

droplet_ids array of integer optional

Example: [3164444,3164445]

An array containing the IDs of the Droplets assigned to the load balancer.

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource will initially be available.

algorithm string, one of: round_robin, least_connections optional Deprecated

Example: round_robin

This field has been deprecated. You can no longer specify an algorithm for load balancers.

created_at string (date-time) optional read-only

Example: 2017-02-01T22:22:58Z

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

disable_lets_encrypt_dns_records boolean optional

Example: true

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains array of object optional

An array of objects specifying the domain configurations for a Global load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination.

is_managed boolean optional

Example: true

A boolean value indicating if the domain is already managed by DigitalOcean. If true, all A and AAAA records required to enable Global load balancers will be automatically added.

name string optional

Example: example.com

FQDN to associate with a Global load balancer.

enable_backend_keepalive boolean optional

Example: true

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol boolean optional

Example: true

A boolean value indicating whether PROXY Protocol is in use.

firewall object optional

An object specifying allow and deny rules to control traffic to the load balancer.

Show child properties

allow array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for allowing traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

deny array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for denying traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

forwarding_rules array of object required

An array of objects specifying the forwarding rules for a load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

glb_settings object optional

An object specifying forwarding configurations for a Global load balancer.

Show child properties

cdn object optional

An object specifying CDN configurations for a Global load balancer.

Show child properties

is_enabled boolean optional

Example: true

A boolean flag to enable CDN caching.

failover_threshold integer optional

Example: 50

region_priorities object optional

Example: {"fra1":2,"nyc1":1,"sgp1":3}

A map of region string to an integer priority value indicating preference for which regional target a Global load balancer will forward traffic to. A lower value indicates a higher priority.

target_port integer optional

Example: 80

An integer representing the port on the target backends which the load balancer will forward traffic to.

target_protocol string, one of: http, https, http2 optional

Example: http

The protocol used for forwarding traffic from the load balancer to the target backends. The possible values are http, https and http2.

health_check object optional

An object specifying health check settings for the load balancer.

Show child properties

check_interval_seconds integer optional

Example: 10

The number of seconds between between two consecutive health checks.

healthy_threshold integer optional

Example: 3

The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool.

path string optional

Example: /

The path on the backend Droplets to which the load balancer instance will send a request.

port integer optional

Example: 80

An integer representing the port on the backend Droplets on which the health check will attempt a connection.

protocol string, one of: http, https, tcp optional

Example: http

The protocol used for health checks sent to the backend Droplets. The possible values are http, https, or tcp.

response_timeout_seconds integer optional

Example: 5

The number of seconds the load balancer instance will wait for a response until marking a health check as failed.

unhealthy_threshold integer optional

Example: 5

The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool.

http_idle_timeout_seconds integer optional

Example: 90

An integer value which configures the idle timeout for HTTP requests to the target droplets.

id string (uuid) optional read-only

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique ID that can be used to identify and reference a load balancer.

ip string optional read-only

Example: 104.131.186.241

An attribute containing the public-facing IP address of the load balancer.

ipv6 string optional read-only

Example: 2604:a880:800:14::85f5:c000

An attribute containing the public-facing IPv6 address of the load balancer.

name string optional

Example: example-lb-01

A human-readable name for a load balancer instance.

network string, one of: EXTERNAL, INTERNAL optional

Example: EXTERNAL

network_stack string, one of: IPV4, DUALSTACK optional

Example: IPV4

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.

project_id string optional

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

redirect_http_to_https boolean optional

Example: true

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

size string, one of: lb-small, lb-medium, lb-large optional Deprecated

Example: lb-small

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.

size_unit integer optional

Example: 3

status string, one of: new, active, errored optional read-only

Example: new

A status string indicating the current state of the load balancer. This can be new, active, or errored.

sticky_sessions object optional

An object specifying sticky sessions settings for the load balancer.

Show child properties

cookie_name string optional

Example: DO-LB

The name of the cookie sent to the client. This attribute is only returned when using cookies for the sticky sessions type.

cookie_ttl_seconds integer optional

Example: 300

The number of seconds until the cookie set by the load balancer expires. This attribute is only returned when using cookies for the sticky sessions type.

type string, one of: cookies, none optional

Example: cookies

An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are cookies or none.

target_load_balancer_ids array of string optional

Example: ["7dbf91fe-cbdb-48dc-8290-c3a181554905","996fa239-fac3-42a2-b9a1-9fa822268b7a"]

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy string, one of: DEFAULT, STRONG optional

Example: STRONG

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.

type string, one of: REGIONAL, REGIONAL_NETWORK, GLOBAL optional

Example: REGIONAL

vpc_uuid string (uuid) optional

Example: c33931f2-a26a-4e61-b85c-4e95a2ec431b

A string specifying the UUID of the VPC to which the load balancer is assigned.

Assign Droplets by Tag

tag string optional

Example: prod:web

The name of a Droplet tag corresponding to Droplets assigned to the load balancer.

region string (enum) optional

Example: nyc3

The slug identifier for the region where the resource will initially be available.

algorithm string, one of: round_robin, least_connections optional Deprecated

Example: round_robin

This field has been deprecated. You can no longer specify an algorithm for load balancers.

created_at string (date-time) optional read-only

Example: 2017-02-01T22:22:58Z

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

disable_lets_encrypt_dns_records boolean optional

Example: true

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains array of object optional

An array of objects specifying the domain configurations for a Global load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination.

is_managed boolean optional

Example: true

A boolean value indicating if the domain is already managed by DigitalOcean. If true, all A and AAAA records required to enable Global load balancers will be automatically added.

name string optional

Example: example.com

FQDN to associate with a Global load balancer.

enable_backend_keepalive boolean optional

Example: true

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol boolean optional

Example: true

A boolean value indicating whether PROXY Protocol is in use.

firewall object optional

An object specifying allow and deny rules to control traffic to the load balancer.

Show child properties

allow array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for allowing traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

deny array of string optional

Example: ["ip:1.2.3.4","cidr:2.3.0.0/16"]

the rules for denying traffic to the load balancer (in the form 'ip:1.2.3.4' or 'cidr:1.2.0.0/16')

forwarding_rules array of object required

An array of objects specifying the forwarding rules for a load balancer.

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

glb_settings object optional

An object specifying forwarding configurations for a Global load balancer.

Show child properties

cdn object optional

An object specifying CDN configurations for a Global load balancer.

Show child properties

is_enabled boolean optional

Example: true

A boolean flag to enable CDN caching.

failover_threshold integer optional

Example: 50

region_priorities object optional

Example: {"fra1":2,"nyc1":1,"sgp1":3}

A map of region string to an integer priority value indicating preference for which regional target a Global load balancer will forward traffic to. A lower value indicates a higher priority.

target_port integer optional

Example: 80

An integer representing the port on the target backends which the load balancer will forward traffic to.

target_protocol string, one of: http, https, http2 optional

Example: http

The protocol used for forwarding traffic from the load balancer to the target backends. The possible values are http, https and http2.

health_check object optional

An object specifying health check settings for the load balancer.

Show child properties

check_interval_seconds integer optional

Example: 10

The number of seconds between between two consecutive health checks.

healthy_threshold integer optional

Example: 3

The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool.

path string optional

Example: /

The path on the backend Droplets to which the load balancer instance will send a request.

port integer optional

Example: 80

An integer representing the port on the backend Droplets on which the health check will attempt a connection.

protocol string, one of: http, https, tcp optional

Example: http

The protocol used for health checks sent to the backend Droplets. The possible values are http, https, or tcp.

response_timeout_seconds integer optional

Example: 5

The number of seconds the load balancer instance will wait for a response until marking a health check as failed.

unhealthy_threshold integer optional

Example: 5

The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool.

http_idle_timeout_seconds integer optional

Example: 90

An integer value which configures the idle timeout for HTTP requests to the target droplets.

id string (uuid) optional read-only

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique ID that can be used to identify and reference a load balancer.

ip string optional read-only

Example: 104.131.186.241

An attribute containing the public-facing IP address of the load balancer.

ipv6 string optional read-only

Example: 2604:a880:800:14::85f5:c000

An attribute containing the public-facing IPv6 address of the load balancer.

name string optional

Example: example-lb-01

A human-readable name for a load balancer instance.

network string, one of: EXTERNAL, INTERNAL optional

Example: EXTERNAL

network_stack string, one of: IPV4, DUALSTACK optional

Example: IPV4

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.

project_id string optional

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

redirect_http_to_https boolean optional

Example: true

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

size string, one of: lb-small, lb-medium, lb-large optional Deprecated

Example: lb-small

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.

size_unit integer optional

Example: 3

status string, one of: new, active, errored optional read-only

Example: new

A status string indicating the current state of the load balancer. This can be new, active, or errored.

sticky_sessions object optional

An object specifying sticky sessions settings for the load balancer.

Show child properties

cookie_name string optional

Example: DO-LB

The name of the cookie sent to the client. This attribute is only returned when using cookies for the sticky sessions type.

cookie_ttl_seconds integer optional

Example: 300

The number of seconds until the cookie set by the load balancer expires. This attribute is only returned when using cookies for the sticky sessions type.

type string, one of: cookies, none optional

Example: cookies

An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are cookies or none.

target_load_balancer_ids array of string optional

Example: ["7dbf91fe-cbdb-48dc-8290-c3a181554905","996fa239-fac3-42a2-b9a1-9fa822268b7a"]

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy string, one of: DEFAULT, STRONG optional

Example: STRONG

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.

type string, one of: REGIONAL, REGIONAL_NETWORK, GLOBAL optional

Example: REGIONAL

vpc_uuid string (uuid) optional

Example: c33931f2-a26a-4e61-b85c-4e95a2ec431b

A string specifying the UUID of the VPC to which the load balancer is assigned.

Request: `/v2/load_balancers/{lb_id}`

Payload

Content type application/json

{
  "algorithm": "round_robin",
  "droplet_ids": [
    3164444,
    3164445
  ],
  "enable_backend_keepalive": true,
  "enable_proxy_protocol": true,
  "firewall": {
    "allow": [
      "ip:1.2.3.4",
      "cidr:2.3.4.0/24"
    ],
    "deny": [
      "cidr:1.2.0.0/16",
      "ip:2.3.4.5"
    ]
  },
  "forwarding_rules": [
    {
      "certificate_id": "",
      "entry_port": 80,
      "entry_protocol": "http",
      "target_port": 80,
      "target_protocol": "http",
      "tls_passthrough": false
    },
    {
      "certificate_id": "",
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 443,
      "target_protocol": "https",
      "tls_passthrough": true
    }
  ],
  "health_check": {
    "check_interval_seconds": 10,
    "healthy_threshold": 5,
    "path": "/",
    "port": 80,
    "protocol": "http",
    "response_timeout_seconds": 5,
    "unhealthy_threshold": 3
  },
  "http_idle_timeout_seconds": 60,
  "name": "updated-example-lb-01",
  "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
  "redirect_http_to_https": false,
  "region": "nyc3",
  "sticky_sessions": {
    "type": "none"
  },
  "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"example-lb-01","size_unit":"2","region":"nyc3","algorithm":"least_connections","forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80},{"entry_protocol":"https","entry_port":444,"target_protocol":"https","target_port":443,"tls_passthrough":true}],"health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3},"sticky_sessions":{"type":"cookies", "cookie_name": "DO_LB", "cookie_ttl_seconds": 300}, "firewall":{"deny":["ip:1.2.3.4","cidr:2.3.4.0/24"], "allow":["cidr:1.2.0.0/16","ip:2.3.4.5"]}, "droplet_ids": [3164444, 3164445]}' \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    updateRequest := &godo.LoadBalancerRequest{
        Name:      "example-01",
        SizeUnit: "2",
        Algorithm: "round_robin",
        Region:    "nyc3",
        ForwardingRules: []godo.ForwardingRule{
            {
                EntryProtocol:  "http",
                EntryPort:      80,
                TargetProtocol: "http",
                TargetPort:     80,
            },
            {
                EntryProtocol:  "https",
                EntryPort:      443,
                TargetProtocol: "https",
                TargetPort:     443,
                TlsPassthrough: true,
            },
        },
        HealthCheck: &godo.HealthCheck{
            Protocol:               "http",
            Port:                   80,
            Path:                   "/",
            CheckIntervalSeconds:   10,
            ResponseTimeoutSeconds: 5,
            HealthyThreshold:       5,
            UnhealthyThreshold:     3,
        },
        StickySessions: &godo.StickySessions{
            Type:             "cookies",
            CookieName:       "DO_LB",
            CookieTtlSeconds: 300,
        },
        DropletIDs:          []int{3164444, 3164445},
        RedirectHttpToHttps: false,
        Firewall:            &godo.LBFirewall{
            Deny: []string{"ip:1.2.3.4", "cidr:2.3.4.0/24"},
            Allow: []string{"cidr:1.2.0.0/16", "ip:2.3.4.5"},
        }
    }

    lb, _, err := c.LoadBalancers.Update(ctx, "c2c97ca7-6f63-4e23-8909-906fd86efb5e", updateRequest)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

load_balancer = DropletKit::LoadBalancer.new(
  name: 'example-lb-01',
  size_unit: '2',
  algorithm: 'round_robin',
  droplet_ids: [ 3164444, 3164445],
  redirect_http_to_https: true,
  region: 'nyc3',
  forwarding_rules: [
    DropletKit::ForwardingRule.new(
      entry_protocol: 'http',
      entry_port: 80,
      target_protocol: 'http',
      target_port: 80,
      certificate_id: '',
      tls_passthrough: false
    ),
    DropletKit::ForwardingRule.new(
      entry_protocol: 'https',
      entry_port: 443,
      target_protocol: 'https',
      target_port: 443,
      certificate_id: '',
      tls_passthrough: true
    )
  ],
  sticky_sessions: DropletKit::StickySession.new(
    type: 'cookies',
    cookie_name: 'DO-LB-COOKIE',
    cookie_ttl_seconds: 5
  ),
  health_check: DropletKit::HealthCheck.new(
    protocol: 'http',
    port: 80,
    path: '/',
    check_interval_seconds: 10,
    response_timeout_seconds: 5,
    healthy_threshold: 5,
    unhealthy_threshold: 3
  )
)
client.load_balancers.update(load_balancer, id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "name": "updated-example-lb-01",
  "region": "nyc3",
  "droplet_ids": [
    3164444,
    3164445
  ],
  "algorithm": "round_robin",
  "forwarding_rules": [
    {
      "entry_protocol": "http",
      "entry_port": 80,
      "target_protocol": "http",
      "target_port": 80,
      "certificate_id": "",
      "tls_passthrough": false
    },
    {
      "entry_protocol": "https",
      "entry_port": 443,
      "target_protocol": "https",
      "target_port": 443,
      "certificate_id": "",
      "tls_passthrough": true
    }
  ],
  "health_check": {
    "protocol": "http",
    "port": 80,
    "path": "/",
    "check_interval_seconds": 10,
    "response_timeout_seconds": 5,
    "healthy_threshold": 5,
    "unhealthy_threshold": 3
  },
  "sticky_sessions": {
    "type": "none"
  },
  "redirect_http_to_https": False,
  "enable_proxy_protocol": True,
  "enable_backend_keepalive": True,
  "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b",
  "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
  "http_idle_timeout_seconds": 60,
  "firewall": {
    "deny": [
      "cidr:1.2.0.0/16",
      "ip:2.3.4.5"
    ],
    "allow": [
      "ip:1.2.3.4",
      "cidr:2.3.4.0/24"
    ]
  }
}
resp = client.load_balancers.update(lb_id="fda9fda", body=req)

Responses

200

The response will be a JSON object with a key called load_balancer. The value of this will be an object containing the standard attributes of a load balancer.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

load_balancer object optional

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

200

{
  "load_balancer": {
    "algorithm": "round_robin",
    "created_at": "2017-02-01T22:22:58Z",
    "disable_lets_encrypt_dns_records": false,
    "droplet_ids": [
      3164444,
      3164445
    ],
    "enable_backend_keepalive": true,
    "enable_proxy_protocol": true,
    "firewall": {
      "allow": [
        "ip:1.2.3.4",
        "cidr:2.3.4.0/24"
      ],
      "deny": [
        "cidr:1.2.0.0/16",
        "ip:2.3.4.5"
      ]
    },
    "forwarding_rules": [
      {
        "certificate_id": "",
        "entry_port": 80,
        "entry_protocol": "http",
        "target_port": 80,
        "target_protocol": "http",
        "tls_passthrough": false
      },
      {
        "certificate_id": "",
        "entry_port": 443,
        "entry_protocol": "https",
        "target_port": 443,
        "target_protocol": "https",
        "tls_passthrough": true
      }
    ],
    "health_check": {
      "check_interval_seconds": 10,
      "healthy_threshold": 5,
      "path": "/",
      "port": 80,
      "protocol": "http",
      "response_timeout_seconds": 5,
      "unhealthy_threshold": 3
    },
    "http_idle_timeout_seconds": 60,
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "ip": "104.131.186.241",
    "name": "updated-example-lb-01",
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "redirect_http_to_https": false,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "slug": "nyc3"
    },
    "size": "lb-small",
    "status": "new",
    "sticky_sessions": {
      "type": "none"
    },
    "tag": "",
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Load Balancer

/v2/load_balancers/{lb_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a load balancer instance, disassociating any Droplets assigned to it and removing it from your account, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID.

A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request: `/v2/load_balancers/{lb_id}`

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.LoadBalancers.Delete(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6")
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.load_balancers.delete(id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.load_balancers.delete(lb_id="afda3ad")

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Global Load Balancer CDN Cache

/v2/load_balancers/{lb_id}/cache

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a Global load balancer CDN cache, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/cache.

A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request: `/v2/load_balancers/{lb_id}/cache`

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/cache"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    _, err := client.LoadBalancers.PurgeCache(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6")
}

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Add Droplets to a Load Balancer

/v2/load_balancers/{lb_id}/droplets

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To assign a Droplet to a load balancer instance, send a POST request to /v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs. Individual Droplets can not be added to a load balancer configured with a Droplet tag. Attempting to do so will result in a "422 Unprocessable Entity" response from the API.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request Body: `application/json`

droplet_ids array of integer required

Example: [3164444,3164445]

An array containing the IDs of the Droplets assigned to the load balancer.

Request: `/v2/load_balancers/{lb_id}/droplets`

Payload

Content type application/json

{
  "droplet_ids": [
    3164444,
    3164445
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"droplet_ids": [3164446, 3164447]}' \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/droplets"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    droplets := []int{3164446, 3164447}
    _, err := client.LoadBalancers.AddDroplets(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", droplets...)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.load_balancers.add_droplets([3164446, 3164447], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "droplet_ids": [
    3164444,
    3164445
  ]
}

resp = client.load_balancers.add_droplets(lb_id="1fd32a", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Remove Droplets from a Load Balancer

/v2/load_balancers/{lb_id}/droplets

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To remove a Droplet from a load balancer instance, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request, there should be a droplet_ids attribute containing a list of Droplet IDs.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request Body: `application/json`

droplet_ids array of integer required

Example: [3164444,3164445]

An array containing the IDs of the Droplets assigned to the load balancer.

Request: `/v2/load_balancers/{lb_id}/droplets`

Payload

Content type application/json

{
  "droplet_ids": [
    3164444,
    3164445
  ]
}

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"droplet_ids": [3164446, 3164447]}' \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/droplets"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    droplets := []int{3164446, 3164447}
    _, err := client.LoadBalancers.RemoveDroplets(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", droplets...)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.load_balancers.remove_droplets([3164446, 3164447], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "droplet_ids": [
    3164444,
    3164445
  ]
}

resp = client.load_balancers.remove_droplets(lb_id="fda9fda", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Add Forwarding Rules to a Load Balancer

/v2/load_balancers/{lb_id}/forwarding_rules

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To add an additional forwarding rule to a load balancer instance, send a POST request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body of the request, there should be a forwarding_rules attribute containing an array of rules to be added.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request Body: `application/json`

forwarding_rules array of object required

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

Request: `/v2/load_balancers/{lb_id}/forwarding_rules`

Payload

Content type application/json

{
  "forwarding_rules": [
    {
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 80,
      "target_protocol": "http",
      "tls_passthrough": false
    }
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"forwarding_rules": [{"entry_protocol": "tcp","entry_port": 3306,"target_protocol": "tcp","target_port": 3306}]}' \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/forwarding_rules"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    forwardingRule := []godo.ForwardingRule{
        {
            EntryProtocol:  "tcp",
            EntryPort:      3306,
            TargetProtocol: "tcp",
            TargetPort:     3306,
        },
    }
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

rule = DropletKit::ForwardingRule.new(
  entry_protocol: 'tcp',
  entry_port: 3306,
  target_protocol: 'tcp',
  target_port: 3306,
  certificate_id: '',
  tls_passthrough: false
)
client.load_balancers.add_forwarding_rules([rule], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "forwarding_rules": [
    {
      "entry_protocol": "https",
      "entry_port": 443,
      "target_protocol": "http",
      "target_port": 80,
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "tls_passthrough": False
    }
  ]
}

resp = client.load_balancers.add_forwarding_rules(lb_id="1fd32a", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Remove Forwarding Rules from a Load Balancer

/v2/load_balancers/{lb_id}/forwarding_rules

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: load_balancer:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

dop_v1_ for personal access tokens generated in the control panel
doo_v1_ for tokens generated by applications using the OAuth flow
dor_v1_ for OAuth refresh tokens

Scopes

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb	CRUD Operation	Scope
GET	Read	`<resource>:read`
POST	Create	`<resource>:create`
PUT/PATCH	Update	`<resource>:update`
DELETE	Delete	`<resource>:delete`

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To remove forwarding rules from a load balancer instance, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body of the request, there should be a forwarding_rules attribute containing an array of rules to be removed.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Path Parameters

lb_id string >= 1 required

Example: 4de7ac8b-495b-4884-9a69-1050c6793cd6

A unique identifier for a load balancer.

Request Body: `application/json`

forwarding_rules array of object required

Show child properties

certificate_id string optional

Example: 892071a0-bb95-49bc-8021-3afd67a210bf

The ID of the TLS certificate used for SSL termination if enabled.

entry_port integer required

Example: 443

An integer representing the port on which the load balancer instance will listen.

entry_protocol string (enum) required

Example: https

target_port integer required

Example: 80

An integer representing the port on the backend Droplets to which the load balancer will send traffic.

target_protocol string, one of: http, https, http2, tcp, udp required

Example: http

tls_passthrough boolean optional

Example: false

A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets.

Request: `/v2/load_balancers/{lb_id}/forwarding_rules`

Payload

Content type application/json

{
  "forwarding_rules": [
    {
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "entry_port": 443,
      "entry_protocol": "https",
      "target_port": 80,
      "target_protocol": "http",
      "tls_passthrough": false
    }
  ]
}

cURL

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"forwarding_rules": [{"entry_protocol": "tcp","entry_port": 3306,"target_protocol": "tcp","target_port": 3306}]}' \
  "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/forwarding_rules"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

func main() {
    token := os.Getenv("DIGITALOCEAN_TOKEN")

    client := godo.NewFromToken(token)
    ctx := context.TODO()

    forwardingRule := []godo.ForwardingRule{
        {
            EntryProtocol:  "tcp",
            EntryPort:      3306,
            TargetProtocol: "tcp",
            TargetPort:     3306,
        },
    }

    _, err := client.LoadBalancers.RemoveForwardingRules(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", forwardingRule...)
}

Ruby

require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

rule = DropletKit::ForwardingRule.new(
  entry_protocol: 'tcp',
  entry_port: 3306,
  target_protocol: 'tcp',
  target_port: 3306,
  certificate_id: '',
  tls_passthrough: false
)
client.load_balancers.remove_forwarding_rules([rule], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')

Python

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "forwarding_rules": [
    {
      "entry_protocol": "https",
      "entry_port": 443,
      "target_protocol": "http",
      "target_port": 80,
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "tls_passthrough": False
    }
  ]
}

resp = client.load_balancers.remove_forwarding_rules(lb_id="fda9fda", body=req)

Responses

204

The action was successful and the response body is empty.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.

Response Headers

ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

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."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

Load Balancers

Endpoints

GET List All Load Balancers

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/load_balancers

Responses

Response

POST Create a New Load Balancer

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/load_balancers

Responses

Response

GET Retrieve an Existing Load Balancer

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/load_balancers/{lb_id}

Responses

Response

PUT Update a Load Balancer

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/load_balancers/{lb_id}

Responses

Response

DELETE Delete a Load Balancer

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/load_balancers/{lb_id}

Responses

Response

DELETE Delete a Global Load Balancer CDN Cache

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/load_balancers/{lb_id}/cache

Responses

Response

POST Add Droplets to a Load Balancer

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/load_balancers/{lb_id}/droplets

Responses

Response

DELETE Remove Droplets from a Load Balancer

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/load_balancers/{lb_id}/droplets

Responses

Response

POST Add Forwarding Rules to a Load Balancer

OAuth Authentication

Scopes

Request: `/v2/load_balancers`

Request Body: `application/json`

Request: `/v2/load_balancers`

Request: `/v2/load_balancers/{lb_id}`

Request Body: `application/json`

Request: `/v2/load_balancers/{lb_id}`

Request: `/v2/load_balancers/{lb_id}`

Request: `/v2/load_balancers/{lb_id}/cache`

Request Body: `application/json`

Request: `/v2/load_balancers/{lb_id}/droplets`

Request Body: `application/json`

Request: `/v2/load_balancers/{lb_id}/droplets`

Request Body: `application/json`

Request: `/v2/load_balancers/{lb_id}/forwarding_rules`

Request Body: `application/json`

Request: `/v2/load_balancers/{lb_id}/forwarding_rules`