Give Feedback

Projects

Generated on 3 Apr 2026

Copy page as Markdown View page as Markdown

Projects allow you to organize your resources into groups that fit the way you work. You can group resources (like Droplets, Spaces, load balancers, domains, and floating IPs) in ways that align with the applications you host on DigitalOcean.

Base URL https://api.digitalocean.com

Endpoints

GET List All Projects POST Create a Project GET Retrieve the Default Project PUT Update the Default Project PATCH Patch the Default Project GET Retrieve an Existing Project PUT Update a Project PATCH Patch a Project DELETE Delete an Existing Project

GET List All Projects

/v2/projects

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 your projects, send a GET request to /v2/projects.

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/projects`

cURL

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

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

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

    client.Projects.List(ctx, opt)
}

Ruby

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

projects = client.projects.all
projects.each

Python

import os
from pydo import Client

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

resp = client.projects.list()

Responses

200

The response will be a JSON object with a key called projects. The value of this will be an object with the standard project 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

projects array of object optional

Show child properties

created_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

description string optional

Example: My website API

The description of the project. The maximum length is 255 characters.

environment string, one of: Development, Staging, Production optional

Example: Production

The environment of the project's resources.

id string (uuid) optional read-only

Example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679

The unique universal identifier of this project.

name string optional

Example: my-web-api

The human-readable name for the project. The maximum length is 175 characters and the name must be unique.

owner_id integer optional read-only

Example: 258992

The integer id of the project owner.

owner_uuid string optional read-only

Example: 99525febec065ca37b2ffe4f852fd2b2581895e7

The unique universal identifier of the project owner.

purpose string optional

Example: Service or API

The purpose of the project. The maximum length is 255 characters. It can have one of the following values:

Just trying out DigitalOcean
Class project / Educational purposes
Website or blog
Web Application
Service or API
Mobile Application
Machine learning / AI / Data processing
IoT
Operational / Developer tooling

If another value for purpose is specified, for example, "your custom purpose", your purpose will be stored as Other: your custom purpose.

updated_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

is_default boolean optional

Example: false

If true, all resources will be added to this project if no project is specified.

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": {
    "pages": {
      "first": "https://api.digitalocean.com/v2/projects?page=1",
      "last": "https://api.digitalocean.com/v2/projects?page=1"
    }
  },
  "meta": {
    "total": 2
  },
  "projects": [
    {
      "created_at": "2018-09-27T20:10:35Z",
      "description": "My website API",
      "environment": "Production",
      "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
      "is_default": false,
      "name": "my-web-api",
      "owner_id": 258992,
      "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
      "purpose": "Service or API",
      "updated_at": "2018-09-27T20:10:35Z"
    },
    {
      "created_at": "2017-10-19T21:44:20Z",
      "description": "Default project",
      "environment": "Development",
      "id": "addb4547-6bab-419a-8542-76263a033cf6",
      "is_default": true,
      "name": "Default",
      "owner_id": 258992,
      "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
      "purpose": "Just trying out DigitalOcean",
      "updated_at": "2019-11-05T18:50:03Z"
    }
  ]
}

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 Project

/v2/projects

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 project, send a POST request to /v2/projects.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

description string optional

Example: My website API

The description of the project. The maximum length is 255 characters.

environment string, one of: Development, Staging, Production optional

Example: Production

The environment of the project's resources.

id string (uuid) optional read-only

Example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679

The unique universal identifier of this project.

name string optional

Example: my-web-api

The human-readable name for the project. The maximum length is 175 characters and the name must be unique.

owner_id integer optional read-only

Example: 258992

The integer id of the project owner.

owner_uuid string optional read-only

Example: 99525febec065ca37b2ffe4f852fd2b2581895e7

The unique universal identifier of the project owner.

purpose string optional

Example: Service or API

The purpose of the project. The maximum length is 255 characters. It can have one of the following values:

Just trying out DigitalOcean
Class project / Educational purposes
Website or blog
Web Application
Service or API
Mobile Application
Machine learning / AI / Data processing
IoT
Operational / Developer tooling

If another value for purpose is specified, for example, "your custom purpose", your purpose will be stored as Other: your custom purpose.

updated_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

Request: `/v2/projects`

Payload

Content type application/json

{
  "description": "My website API",
  "environment": "Production",
  "name": "my-web-api",
  "purpose": "Service or API"
}

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Production"}' \
  "https://api.digitalocean.com/v2/projects"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    createReq := &godo.CreateProjectRequest{
      Name:        "my-web-api",
      Description: "My website API",
      Purpose:     "Service or API",
      Environment: "Production",
    }

    client.Projects.Create(ctx, createReq)
}

Ruby

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

project = DropletKit::Project.new(
  name: 'my-api',
  description: 'My website API',
  purpose: 'Service or API',
  environment: 'Production'
)
client.projects.create(project)

Python

import os
from pydo import Client

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

req = {
  "name": "my-web-api",
  "description": "My website API",
  "purpose": "Service or API",
  "environment": "Production"
}

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

Responses

201

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

201

{
  "project": {
    "created_at": "2018-09-27T20:10:35Z",
    "description": "My website API",
    "environment": "Production",
    "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
    "is_default": false,
    "name": "my-web-api",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Service or API",
    "updated_at": "2018-09-27T20:10:35Z"
  }
}

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 the Default Project

/v2/projects/default

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 get your default project, send a GET request to /v2/projects/default.

Request: `/v2/projects/default`

cURL

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

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    client.Projects.GetDefault(ctx)
}

Ruby

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

client.projects.find_default

Python

import os
from pydo import Client

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

resp = client.projects.get_default()

Responses

200

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

{
  "project": {
    "created_at": "2017-10-19T21:44:20Z",
    "description": "Default project",
    "environment": "Development",
    "id": "addb4547-6bab-419a-8542-76263a033cf6",
    "is_default": true,
    "name": "Default",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Just trying out DigitalOcean",
    "updated_at": "2019-11-05T18:50:03Z"
  }
}

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 the Default Project

/v2/projects/default

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 you default project, send a PUT request to /v2/projects/default. All of the following attributes must be sent.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

description string optional

Example: My website API

The description of the project. The maximum length is 255 characters.

environment string, one of: Development, Staging, Production optional

Example: Production

The environment of the project's resources.

id string (uuid) optional read-only

Example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679

The unique universal identifier of this project.

name string optional

Example: my-web-api

The human-readable name for the project. The maximum length is 175 characters and the name must be unique.

owner_id integer optional read-only

Example: 258992

The integer id of the project owner.

owner_uuid string optional read-only

Example: 99525febec065ca37b2ffe4f852fd2b2581895e7

The unique universal identifier of the project owner.

purpose string optional

Example: Service or API

The purpose of the project. The maximum length is 255 characters. It can have one of the following values:

Just trying out DigitalOcean
Class project / Educational purposes
Website or blog
Web Application
Service or API
Mobile Application
Machine learning / AI / Data processing
IoT
Operational / Developer tooling

If another value for purpose is specified, for example, "your custom purpose", your purpose will be stored as Other: your custom purpose.

updated_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

is_default boolean optional

Example: false

If true, all resources will be added to this project if no project is specified.

Request: `/v2/projects/default`

Payload

Content type application/json

{
  "description": "My website API",
  "environment": "Production",
  "is_default": false,
  "name": "my-web-api",
  "purpose": "Service or API"
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Staging", "is_default": false}' \
  "https://api.digitalocean.com/v2/projects/default"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    updateReq := &godo.UpdateProjectRequest{
      Name:        "my-web-api",
      Description: "My website API",
      Purpose:     "Service or API",
      Environment: "Staging",
      IsDefault:   false,
    }

    client.Projects.Update(ctx, godo.DefaultProject, updateReq)
}

Ruby

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

project = client.projects.find_default
project.environment = 'Staging'
client.projects.update(project, id: 'default')

Python

import os
from pydo import Client

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

req = {
  "name": "my-web-api",
  "description": "My website API",
  "purpose": "Service or API",
  "environment": "Production",
  "is_default": False
}

resp = client.projects.update_default(body=req)

Responses

200

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

{
  "project": {
    "created_at": "2018-09-27T20:10:35Z",
    "description": "My website API",
    "environment": "Production",
    "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
    "is_default": false,
    "name": "my-web-api",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Service or API",
    "updated_at": "2018-09-27T20:10:35Z"
  }
}

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

PATCH Patch the Default Project

/v2/projects/default

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 only specific attributes of your default project, send a PATCH request to /v2/projects/default. At least one of the following attributes needs to be sent.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

description string optional

Example: My website API

The description of the project. The maximum length is 255 characters.

environment string, one of: Development, Staging, Production optional

Example: Production

The environment of the project's resources.

id string (uuid) optional read-only

Example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679

The unique universal identifier of this project.

name string optional

Example: my-web-api

The human-readable name for the project. The maximum length is 175 characters and the name must be unique.

owner_id integer optional read-only

Example: 258992

The integer id of the project owner.

owner_uuid string optional read-only

Example: 99525febec065ca37b2ffe4f852fd2b2581895e7

The unique universal identifier of the project owner.

purpose string optional

Example: Service or API

The purpose of the project. The maximum length is 255 characters. It can have one of the following values:

Just trying out DigitalOcean
Class project / Educational purposes
Website or blog
Web Application
Service or API
Mobile Application
Machine learning / AI / Data processing
IoT
Operational / Developer tooling

If another value for purpose is specified, for example, "your custom purpose", your purpose will be stored as Other: your custom purpose.

updated_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

is_default boolean optional

Example: false

If true, all resources will be added to this project if no project is specified.

Request: `/v2/projects/default`

Payload

Content type application/json

{
  "name": "my-web-api"
}

cURL

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"environment": "Staging"}' \
  "https://api.digitalocean.com/v2/projects/default"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    updateReq := &godo.UpdateProjectRequest{
      Environment: "Staging",
    }

    client.Projects.Update(ctx, godo.DefaultProject, updateReq)
}

Ruby

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

project = client.projects.find_default
project.environment = 'Staging'
client.projects.update(project, id: 'default')

Python

import os
from pydo import Client

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

req = {
  "name": "my-web-api"
}

resp = client.projects.patch_default(body=req)

Responses

200

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

{
  "project": {
    "created_at": "2018-09-27T20:10:35Z",
    "description": "My website API",
    "environment": "Production",
    "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
    "is_default": false,
    "name": "my-web-api",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Service or API",
    "updated_at": "2018-09-27T20:10:35Z"
  }
}

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

GET Retrieve an Existing Project

/v2/projects/{project_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 get a project, send a GET request to /v2/projects/$PROJECT_ID.

Path Parameters

project_id string (uuid) >= 1 required

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

A unique identifier for a project.

Request: `/v2/projects/{project_id}`

cURL

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    client.Projects.Get(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679")
}

Ruby

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

project = client.projects.find(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')

Python

import os
from pydo import Client

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

resp = client.projects.get(project_id="4e1bfbc3")

Responses

200

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

{
  "project": {
    "created_at": "2018-09-27T20:10:35Z",
    "description": "My website API",
    "environment": "Production",
    "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
    "is_default": false,
    "name": "my-web-api",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Service or API",
    "updated_at": "2018-09-27T20:10:35Z"
  }
}

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 Project

/v2/projects/{project_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 project, send a PUT request to /v2/projects/$PROJECT_ID. All of the following attributes must be sent.

Path Parameters

project_id string (uuid) >= 1 required

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

A unique identifier for a project.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

description string optional

Example: My website API

The description of the project. The maximum length is 255 characters.

environment string, one of: Development, Staging, Production optional

Example: Production

The environment of the project's resources.

id string (uuid) optional read-only

Example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679

The unique universal identifier of this project.

name string optional

Example: my-web-api

The human-readable name for the project. The maximum length is 175 characters and the name must be unique.

owner_id integer optional read-only

Example: 258992

The integer id of the project owner.

owner_uuid string optional read-only

Example: 99525febec065ca37b2ffe4f852fd2b2581895e7

The unique universal identifier of the project owner.

purpose string optional

Example: Service or API

The purpose of the project. The maximum length is 255 characters. It can have one of the following values:

Just trying out DigitalOcean
Class project / Educational purposes
Website or blog
Web Application
Service or API
Mobile Application
Machine learning / AI / Data processing
IoT
Operational / Developer tooling

If another value for purpose is specified, for example, "your custom purpose", your purpose will be stored as Other: your custom purpose.

updated_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

is_default boolean optional

Example: false

If true, all resources will be added to this project if no project is specified.

Request: `/v2/projects/{project_id}`

Payload

Content type application/json

{
  "description": "My website API",
  "environment": "Production",
  "is_default": false,
  "name": "my-web-api",
  "purpose": "Service or API"
}

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Staging", "is_default": false}' \
  "https://api.digitalocean.com/v2/projects/4e1bfbc3\
  -dc3e-41f2-a18f-1b4d7ba71679"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    updateReq := &godo.UpdateProjectRequest{
      Name:        "my-web-api",
      Description: "My website API",
      Purpose:     "Service or API",
      Environment: "Staging",
      IsDefault:   false,
    }

    client.Projects.Update(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", updateReq)

}

Ruby

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

project = client.projects.find(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')
project.environment = 'Staging'
client.projects.update(project, id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')

Python

import os
from pydo import Client

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

req = {
  "name": "my-web-api",
  "description": "My website API",
  "purpose": "Service or API",
  "environment": "Production",
  "is_default": False
}

resp = client.projects.update_default(body=req)

Responses

200

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

{
  "project": {
    "created_at": "2018-09-27T20:10:35Z",
    "description": "My website API",
    "environment": "Production",
    "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
    "is_default": false,
    "name": "my-web-api",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Service or API",
    "updated_at": "2018-09-27T20:10:35Z"
  }
}

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

PATCH Patch a Project

/v2/projects/{project_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 only specific attributes of a project, send a PATCH request to /v2/projects/$PROJECT_ID. At least one of the following attributes needs to be sent.

Path Parameters

project_id string (uuid) >= 1 required

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

A unique identifier for a project.

Request Body: `application/json`

created_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

description string optional

Example: My website API

The description of the project. The maximum length is 255 characters.

environment string, one of: Development, Staging, Production optional

Example: Production

The environment of the project's resources.

id string (uuid) optional read-only

Example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679

The unique universal identifier of this project.

name string optional

Example: my-web-api

The human-readable name for the project. The maximum length is 175 characters and the name must be unique.

owner_id integer optional read-only

Example: 258992

The integer id of the project owner.

owner_uuid string optional read-only

Example: 99525febec065ca37b2ffe4f852fd2b2581895e7

The unique universal identifier of the project owner.

purpose string optional

Example: Service or API

The purpose of the project. The maximum length is 255 characters. It can have one of the following values:

Just trying out DigitalOcean
Class project / Educational purposes
Website or blog
Web Application
Service or API
Mobile Application
Machine learning / AI / Data processing
IoT
Operational / Developer tooling

If another value for purpose is specified, for example, "your custom purpose", your purpose will be stored as Other: your custom purpose.

updated_at string (date-time) optional read-only

Example: 2018-09-27T20:10:35Z

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

is_default boolean optional

Example: false

If true, all resources will be added to this project if no project is specified.

Request: `/v2/projects/{project_id}`

Payload

Content type application/json

{
  "name": "my-web-api"
}

cURL

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"environment": "Staging"}' \
  "https://api.digitalocean.com/v2/projects/4e1bfbc3\
  -dc3e-41f2-a18f-1b4d7ba71679"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    updateReq := &godo.UpdateProjectRequest{
      Environment: "Staging",
    }

    client.Projects.Update(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", updateReq)
}

Ruby

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

project = client.projects.find(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')
project.environment = 'Staging'
client.projects.update(project, id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')

Python

import os
from pydo import Client

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

req = {
  "name": "my-web-api"
}

resp = client.projects.patch(project_id="4e1bfbc3", body=req)

Responses

200

The response will be a JSON object with a key called project. The value of this will be an object with the standard project 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

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

project 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

{
  "project": {
    "created_at": "2018-09-27T20:10:35Z",
    "description": "My website API",
    "environment": "Production",
    "id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
    "is_default": false,
    "name": "my-web-api",
    "owner_id": 258992,
    "owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
    "purpose": "Service or API",
    "updated_at": "2018-09-27T20:10:35Z"
  }
}

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 an Existing Project

/v2/projects/{project_id}

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: project: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 project, send a DELETE request to /v2/projects/$PROJECT_ID. To be deleted, a project must not have any resources assigned to it. Any existing resources must first be reassigned or destroyed, or you will receive a 412 error.

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

Path Parameters

project_id string (uuid) >= 1 required

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

A unique identifier for a project.

Request: `/v2/projects/{project_id}`

cURL

curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679"

import (
    "context"
    "os"

    "github.com/digitalocean/godo"
)

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

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

    _, err := client.Projects.Delete(ctx, '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')
}

Ruby

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

client.projects.delete(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')

Python

import os
from pydo import Client

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

resp = client.projects.delete(project_id="fda9fda")

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.

412

Only an empty project can be deleted.

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

412

{
  "id": "precondition_failed",
  "message": "cannot delete a project with resources. move or remove the resources first"
}

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

Projects

Endpoints

GET List All Projects

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/projects

Responses

Response

POST Create a Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/projects

Responses

Response

GET Retrieve the Default Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request: /v2/projects/default

Responses

Response

PUT Update the Default Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/projects/default

Responses

Response

PATCH Patch the Default Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/projects/default

Responses

Response

GET Retrieve an Existing Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/projects/{project_id}

Responses

Response

PUT Update a Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/projects/{project_id}

Responses

Response

PATCH Patch a Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/projects/{project_id}

Responses

Response

DELETE Delete an Existing Project

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request: `/v2/projects`

Request Body: `application/json`

Request: `/v2/projects`

Request: `/v2/projects/default`

Request Body: `application/json`

Request: `/v2/projects/default`

Request Body: `application/json`

Request: `/v2/projects/default`

Request: `/v2/projects/{project_id}`

Request Body: `application/json`

Request: `/v2/projects/{project_id}`

Request Body: `application/json`

Request: `/v2/projects/{project_id}`

Request: `/v2/projects/{project_id}`