Floating IPs

Validated on 19 Jun 2018 • Last edited on 23 Mar 2026

View full API reference

As of 16 June 2022, we have renamed the Floating IP product to [Reserved IPs](/reference/api/reference/reserved-ips/. The Reserved IP product's endpoints function the exact same way as Floating IPs. The only difference is the name change throughout the URLs and fields. For example, the floating_ips field is now the reserved_ips field. The Floating IP endpoints will remain active until fall 2023 before being permanently deprecated.

With the exception of the [Projects API](/reference/api/reference/projects/, we will reflect this change as an additional field in the responses across the API where the floating_ip field is used. For example, the Droplet metadata response will contain the field reserved_ips in addition to the floating_ips field. Floating IPs retrieved using the Projects API will retain the original name.

DigitalOcean Floating IPs are publicly-accessible static IP addresses that can be mapped to one of your Droplets. They can be used to create highly available setups or other configurations requiring movable addresses.

Floating IPs are bound to a specific region.

Base URL https://api.digitalocean.com

Endpoints

GET List All Floating IPs POST Create a New Floating IP GET Retrieve an Existing Floating IP DELETE Delete a Floating IP

GET List All Floating IPs

/v2/floating_ips
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: reserved_ip: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 floating IPs available on your account, send a GET request to /v2/floating_ips.

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/floating_ips
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/floating_ips?page=1&per_page=20" 
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,
    }

    floatingIPs, _, err := client.FloatingIPs.List(ctx, opt)
}
require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

floating_ips = client.floating_ips.all
floating_ips.each

Responses

200

The response will be a JSON object with a key called floating_ips. This will be set to an array of floating IP objects, each of which will contain the standard floating IP 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
floating_ips array of object optional
Show child properties
droplet anyOf optional

The Droplet that the floating IP has been assigned to. When you query a floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null.

Requires droplet:read scope.

One of:
null
Droplet
backup_ids array of integer required
Example: [53893572]

An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.

created_at string (date-time) required
Example: 2020-07-21T18:37:44Z

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

disk integer required
Example: 25

The size of the Droplet's disk in gigabytes.

disk_info array of object optional

An array of objects containing information about the disks available to the Droplet.

Show child properties
size object optional
Additional nested properties not shown. Refer to the full API spec for details.
type string, one of: local, scratch optional
Example: local

The type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.

features array of string required
Example: ["backups","private_networking","ipv6"]

An array of features enabled on this Droplet.

gpu_info object optional

An object containing information about the GPU capabilities of Droplets created with this size.

Show child properties
count integer optional
Example: 1

The number of GPUs allocated to the Droplet.

model string optional
Example: nvidia_h100

The model of the GPU.

vram object optional
Additional nested properties not shown. Refer to the full API spec for details.
id integer required
Example: 3164444

A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.

image object required
kernel object optional Deprecated Nullable

Note: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to null.

The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.

Show child properties
id integer optional
Example: 7515

A unique number used to identify and reference a specific kernel.

name string optional
Example: DigitalOcean GrubLoader v0.2 (20160714)

The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.

version string optional
Example: 2016.07.13-DigitalOcean_loader_Ubuntu

A standard kernel version string representing the version, patch, and release information.

locked boolean required
Example: false

A boolean value indicating whether the Droplet has been locked, preventing actions by users.

memory integer required
Example: 1024

Memory of the Droplet in megabytes.

name string required
Example: example.com

The human-readable name set for the Droplet instance.

networks object required

The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

Show child properties
v4 array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
v6 array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
next_backup_window object required
region object required
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

Additional nested properties not shown. Refer to the full API spec for details.
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.

Additional nested properties not shown. Refer to the full API spec for details.
slug string required
Example: nyc3

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

size object required
Show child properties
available boolean required
Example: true

This is a boolean value that represents whether new Droplets can be created with this size.

description string required
Example: Basic

A string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.

disk integer required
Example: 25

The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.

disk_info array of object optional

An array of objects containing information about the disks available to Droplets created with this size.

Additional nested properties not shown. Refer to the full API spec for details.
gpu_info object optional

An object containing information about the GPU capabilities of Droplets created with this size.

Additional nested properties not shown. Refer to the full API spec for details.
memory integer required
Example: 1024

The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.

price_hourly number (float) required
Example: 0.00743999984115362

This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.

price_monthly number (float) required
Example: 5

This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.

regions array of string required
Example: ["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]

An array containing the region slugs where this size is available for Droplet creates.

Additional nested properties not shown. Refer to the full API spec for details.
slug string required
Example: s-1vcpu-1gb

A human-readable string that is used to uniquely identify each size.

transfer number (float) required
Example: 1

The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.

vcpus integer required
Example: 1

The number of CPUs allocated to Droplets of this size.

size_slug string required
Example: s-1vcpu-1gb

The unique slug identifier for the size of this Droplet.

snapshot_ids array of integer required
Example: [67512819]

An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.

status string, one of: new, active, off, archive required
Example: active

A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".

tags array of string required
Example: ["web","env:prod"]

An array of Tags the Droplet has been tagged with.
Requires tag:read scope.

vcpus integer required
Example: 1

The number of virtual CPUs.

volume_ids array of string required
Example: ["506f78a4-e098-11e5-ad9f-000f53306ae1"]

A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.

ip string (ipv4) optional
Example: 45.55.96.47

The public IP address of the floating IP. It also serves as its identifier.

locked boolean optional
Example: true

A boolean value indicating whether or not the floating IP has pending actions preventing new ones from being submitted.

project_id string (uuid) optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The UUID of the project to which the reserved IP currently belongs.

Requires project:read scope.

region object optional
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

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

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

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

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
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
{
  "floating_ips": [
    {
      "droplet": null,
      "ip": "45.55.96.47",
      "locked": false,
      "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
      "region": {
        "available": true,
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "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-192g"
        ],
        "slug": "nyc3"
      }
    }
  ],
  "links": {},
  "meta": {
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a New Floating IP

/v2/floating_ips
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: reserved_ip:create

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"

On creation, a floating IP must be either assigned to a Droplet or reserved to a region.

  • To create a new floating IP assigned to a Droplet, send a POST request to /v2/floating_ips with the droplet_id attribute.

  • To create a new floating IP reserved to a region, send a POST request to /v2/floating_ips with the region attribute.

Request Body: application/json

droplet_id integer required
Example: 2457247

The ID of the Droplet that the floating IP will be assigned to.

project_id string (uuid) optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The UUID of the project to which the floating IP will be assigned.

region string required
Example: nyc3

The slug identifier for the region the floating IP will be reserved to.

Request: /v2/floating_ips
Content type application/json 
{
  "droplet_id": 2457247
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"droplet_id": 123456}' \
  "https://api.digitalocean.com/v2/floating_ips" 
import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    createRequest := &godo.FloatingIPCreateRequest{
        DropletID: 123456,

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

floating_ip = DropletKit::FloatingIp.new(droplet_id: 123456)
client.floating_ips.create(floating_ip)

Responses

202

The response will be a JSON object with a key called floating_ip. The value of this will be an object that contains the standard attributes associated with a floating IP. When assigning a floating IP to a Droplet at same time as it created, the response's links object will contain links to both the Droplet and the assignment action. The latter can be used to check the status of the action.
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
floating_ip object optional
Show child properties
droplet anyOf optional

The Droplet that the floating IP has been assigned to. When you query a floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null.

Requires droplet:read scope.

One of:
null
Droplet
backup_ids array of integer required
Example: [53893572]

An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.

created_at string (date-time) required
Example: 2020-07-21T18:37:44Z

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

disk integer required
Example: 25

The size of the Droplet's disk in gigabytes.

disk_info array of object optional

An array of objects containing information about the disks available to the Droplet.

Show child properties
size object optional
Additional nested properties not shown. Refer to the full API spec for details.
type string, one of: local, scratch optional
Example: local

The type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.

features array of string required
Example: ["backups","private_networking","ipv6"]

An array of features enabled on this Droplet.

gpu_info object optional

An object containing information about the GPU capabilities of Droplets created with this size.

Show child properties
count integer optional
Example: 1

The number of GPUs allocated to the Droplet.

model string optional
Example: nvidia_h100

The model of the GPU.

vram object optional
Additional nested properties not shown. Refer to the full API spec for details.
id integer required
Example: 3164444

A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.

image object required
kernel object optional Deprecated Nullable

Note: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to null.

The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.

Show child properties
id integer optional
Example: 7515

A unique number used to identify and reference a specific kernel.

name string optional
Example: DigitalOcean GrubLoader v0.2 (20160714)

The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.

version string optional
Example: 2016.07.13-DigitalOcean_loader_Ubuntu

A standard kernel version string representing the version, patch, and release information.

locked boolean required
Example: false

A boolean value indicating whether the Droplet has been locked, preventing actions by users.

memory integer required
Example: 1024

Memory of the Droplet in megabytes.

name string required
Example: example.com

The human-readable name set for the Droplet instance.

networks object required

The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

Show child properties
v4 array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
v6 array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
next_backup_window object required
region object required
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

Additional nested properties not shown. Refer to the full API spec for details.
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.

Additional nested properties not shown. Refer to the full API spec for details.
slug string required
Example: nyc3

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

size object required
Show child properties
available boolean required
Example: true

This is a boolean value that represents whether new Droplets can be created with this size.

description string required
Example: Basic

A string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.

disk integer required
Example: 25

The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.

disk_info array of object optional

An array of objects containing information about the disks available to Droplets created with this size.

Additional nested properties not shown. Refer to the full API spec for details.
gpu_info object optional

An object containing information about the GPU capabilities of Droplets created with this size.

Additional nested properties not shown. Refer to the full API spec for details.
memory integer required
Example: 1024

The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.

price_hourly number (float) required
Example: 0.00743999984115362

This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.

price_monthly number (float) required
Example: 5

This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.

regions array of string required
Example: ["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]

An array containing the region slugs where this size is available for Droplet creates.

Additional nested properties not shown. Refer to the full API spec for details.
slug string required
Example: s-1vcpu-1gb

A human-readable string that is used to uniquely identify each size.

transfer number (float) required
Example: 1

The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.

vcpus integer required
Example: 1

The number of CPUs allocated to Droplets of this size.

size_slug string required
Example: s-1vcpu-1gb

The unique slug identifier for the size of this Droplet.

snapshot_ids array of integer required
Example: [67512819]

An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.

status string, one of: new, active, off, archive required
Example: active

A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".

tags array of string required
Example: ["web","env:prod"]

An array of Tags the Droplet has been tagged with.
Requires tag:read scope.

vcpus integer required
Example: 1

The number of virtual CPUs.

volume_ids array of string required
Example: ["506f78a4-e098-11e5-ad9f-000f53306ae1"]

A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.

ip string (ipv4) optional
Example: 45.55.96.47

The public IP address of the floating IP. It also serves as its identifier.

locked boolean optional
Example: true

A boolean value indicating whether or not the floating IP has pending actions preventing new ones from being submitted.

project_id string (uuid) optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The UUID of the project to which the reserved IP currently belongs.

Requires project:read scope.

region object optional
links object optional
Show child properties
actions array of object optional
Show child properties
href string (uri) optional
Example: https://api.digitalocean.com/v2/actions/7515

A URL that can be used to access the action.

id integer optional
Example: 7515

A unique numeric ID that can be used to identify and reference an action.

rel string optional
Example: create

A string specifying the type of the related action.

droplets array of object optional
Show child properties
href string (uri) optional
Example: https://api.digitalocean.com/v2/actions/7515

A URL that can be used to access the action.

id integer optional
Example: 7515

A unique numeric ID that can be used to identify and reference an action.

rel string optional
Example: create

A string specifying the type of the related action.

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

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

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

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

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
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
Example 
{
  "floating_ip": {
    "droplet": null,
    "ip": "45.55.96.47",
    "locked": true,
    "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "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-192g"
      ],
      "slug": "nyc3"
    }
  },
  "links": {
    "actions": [
      {
        "href": "https://api.digitalocean.com/v2/actions/1088924622",
        "id": 1088924622,
        "rel": "assign_ip"
      }
    ],
    "droplets": [
      {
        "href": "https://api.digitalocean.com/v2/droplets/213939433",
        "id": 213939433,
        "rel": "droplet"
      }
    ]
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Floating IP

/v2/floating_ips/{floating_ip}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: reserved_ip: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 show information about a floating IP, send a GET request to /v2/floating_ips/$FLOATING_IP_ADDR.

Path Parameters

floating_ip string (ipv4) >= 1 required
Example: 45.55.96.47

A floating IP address.

Request: /v2/floating_ips/{floating_ip}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/floating_ips/45.55.96.47" 
import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    floatingIP, _, err := client.FloatingIPs.Get(ctx, "45.55.96.47")
}
require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.floating_ips.find(ip: '45.55.96.47')

Responses

200

The response will be a JSON object with a key called floating_ip. The value of this will be an object that contains the standard attributes associated with a floating IP.
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
floating_ip object optional
Show child properties
droplet anyOf optional

The Droplet that the floating IP has been assigned to. When you query a floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null.

Requires droplet:read scope.

One of:
null
Droplet
backup_ids array of integer required
Example: [53893572]

An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.

created_at string (date-time) required
Example: 2020-07-21T18:37:44Z

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

disk integer required
Example: 25

The size of the Droplet's disk in gigabytes.

disk_info array of object optional

An array of objects containing information about the disks available to the Droplet.

Show child properties
size object optional
Additional nested properties not shown. Refer to the full API spec for details.
type string, one of: local, scratch optional
Example: local

The type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.

features array of string required
Example: ["backups","private_networking","ipv6"]

An array of features enabled on this Droplet.

gpu_info object optional

An object containing information about the GPU capabilities of Droplets created with this size.

Show child properties
count integer optional
Example: 1

The number of GPUs allocated to the Droplet.

model string optional
Example: nvidia_h100

The model of the GPU.

vram object optional
Additional nested properties not shown. Refer to the full API spec for details.
id integer required
Example: 3164444

A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.

image object required
kernel object optional Deprecated Nullable

Note: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to null.

The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.

Show child properties
id integer optional
Example: 7515

A unique number used to identify and reference a specific kernel.

name string optional
Example: DigitalOcean GrubLoader v0.2 (20160714)

The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.

version string optional
Example: 2016.07.13-DigitalOcean_loader_Ubuntu

A standard kernel version string representing the version, patch, and release information.

locked boolean required
Example: false

A boolean value indicating whether the Droplet has been locked, preventing actions by users.

memory integer required
Example: 1024

Memory of the Droplet in megabytes.

name string required
Example: example.com

The human-readable name set for the Droplet instance.

networks object required

The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.

Show child properties
v4 array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
v6 array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
next_backup_window object required
region object required
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

Additional nested properties not shown. Refer to the full API spec for details.
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.

Additional nested properties not shown. Refer to the full API spec for details.
slug string required
Example: nyc3

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

size object required
Show child properties
available boolean required
Example: true

This is a boolean value that represents whether new Droplets can be created with this size.

description string required
Example: Basic

A string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.

disk integer required
Example: 25

The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.

disk_info array of object optional

An array of objects containing information about the disks available to Droplets created with this size.

Additional nested properties not shown. Refer to the full API spec for details.
gpu_info object optional

An object containing information about the GPU capabilities of Droplets created with this size.

Additional nested properties not shown. Refer to the full API spec for details.
memory integer required
Example: 1024

The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.

price_hourly number (float) required
Example: 0.00743999984115362

This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.

price_monthly number (float) required
Example: 5

This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.

regions array of string required
Example: ["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]

An array containing the region slugs where this size is available for Droplet creates.

Additional nested properties not shown. Refer to the full API spec for details.
slug string required
Example: s-1vcpu-1gb

A human-readable string that is used to uniquely identify each size.

transfer number (float) required
Example: 1

The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.

vcpus integer required
Example: 1

The number of CPUs allocated to Droplets of this size.

size_slug string required
Example: s-1vcpu-1gb

The unique slug identifier for the size of this Droplet.

snapshot_ids array of integer required
Example: [67512819]

An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.

status string, one of: new, active, off, archive required
Example: active

A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".

tags array of string required
Example: ["web","env:prod"]

An array of Tags the Droplet has been tagged with.
Requires tag:read scope.

vcpus integer required
Example: 1

The number of virtual CPUs.

volume_ids array of string required
Example: ["506f78a4-e098-11e5-ad9f-000f53306ae1"]

A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.

vpc_uuid string optional
Example: 760e09ef-dc84-11e8-981e-3cfdfeaae000

A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.

ip string (ipv4) optional
Example: 45.55.96.47

The public IP address of the floating IP. It also serves as its identifier.

locked boolean optional
Example: true

A boolean value indicating whether or not the floating IP has pending actions preventing new ones from being submitted.

project_id string (uuid) optional
Example: 746c6152-2fa2-11ed-92d3-27aaa54e4988

The UUID of the project to which the reserved IP currently belongs.

Requires project:read scope.

region 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

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

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

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

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

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
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
Example 
{
  "floating_ip": {
    "droplet": {
      "backup_ids": [
        53893572
      ],
      "created_at": "2020-07-21T18:37:44Z",
      "disk": 25,
      "features": [
        "backups",
        "private_networking",
        "ipv6"
      ],
      "id": 3164444,
      "image": {
        "created_at": "2020-05-15T05:47:50Z",
        "description": "",
        "distribution": "Ubuntu",
        "error_message": "",
        "id": 63663980,
        "min_disk_size": 20,
        "name": "20.04 (LTS) x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "size_gigabytes": 2.36,
        "slug": "ubuntu-20-04-x64",
        "status": "available",
        "tags": [],
        "type": "base"
      },
      "kernel": null,
      "locked": false,
      "memory": 1024,
      "name": "example.com",
      "networks": {
        "v4": [
          {
            "gateway": "nil",
            "ip_address": "10.128.192.124",
            "netmask": "255.255.0.0",
            "type": "private"
          },
          {
            "gateway": "192.241.165.1",
            "ip_address": "192.241.165.154",
            "netmask": "255.255.255.0",
            "type": "public"
          }
        ],
        "v6": [
          {
            "gateway": "2604:a880:0:1010::1",
            "ip_address": "2604:a880:0:1010::18a:a001",
            "netmask": 64,
            "type": "public"
          }
        ]
      },
      "next_backup_window": {
        "end": "2020-07-30T23:00:00Z",
        "start": "2020-07-30T00:00:00Z"
      },
      "region": {
        "available": true,
        "features": [
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "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-192g"
        ],
        "slug": "nyc3"
      },
      "size": {
        "available": true,
        "description": "Basic",
        "disk": 25,
        "memory": 1024,
        "price_hourly": 0.00743999984115362,
        "price_monthly": 5,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "slug": "s-1vcpu-1gb",
        "transfer": 1,
        "vcpus": 1
      },
      "size_slug": "s-1vcpu-1gb",
      "snapshot_ids": [
        67512819
      ],
      "status": "active",
      "tags": [
        "web",
        "env:prod"
      ],
      "vcpus": 1,
      "volume_ids": [],
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
    },
    "ip": "45.55.96.47",
    "locked": false,
    "project_id": "746c6152-2fa2-11ed-92d3-27aaa54e4988",
    "region": {
      "available": true,
      "features": [
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "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-192g"
      ],
      "slug": "nyc3"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Floating IP

/v2/floating_ips/{floating_ip}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: reserved_ip:delete

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 delete a floating IP and remove it from your account, send a DELETE request to /v2/floating_ips/$FLOATING_IP_ADDR.

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

Path Parameters

floating_ip string (ipv4) >= 1 required
Example: 45.55.96.47

A floating IP address.

Request: /v2/floating_ips/{floating_ip}
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/floating_ips/45.55.96.47"
import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    _, err := client.FloatingIPs.Delete(ctx, "45.55.96.34")
}
require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)

client.floating_ips.delete(ip: '45.55.96.47')

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

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.

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

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

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

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

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

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
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
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

We can't find any results for your search.

Try using different keywords or simplifying your search terms.