Digital Ocean Project Resources API

openapi: 3.2.0
info:
  title: DigitalOcean Project Resources API
  version: '2.0'
  description: '# Introduction


    The DigitalOcean API allows you to manage Droplets and resources within the

    DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests.'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: DigitalOcean API Team
    email: api-engineering@digitalocean.com
  termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/
servers:
- url: https://api.digitalocean.com
  description: production
security:
- bearer_auth: []
tags:
- name: Project Resources
  description: Project Resources are resources that can be grouped into your projects.
paths:
  /v2/projects/{project_id}/resources:
    get:
      operationId: projects_list_resources
      summary: List Project Resources
      description: To list all your resources in a project, send a GET request to `/v2/projects/$PROJECT_ID/resources`.
      tags:
      - Project Resources
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          $ref: '#/components/responses/resources_list'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
        '500':
          $ref: '#/components/responses/server_error'
        default:
          $ref: '#/components/responses/unexpected_error'
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  \"https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources\""
      - lang: Go
        source: "import (\n    \"context\"\n    \"os\"\n\n    \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n    token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n    client := godo.NewFromToken(token)\n    ctx := context.TODO()\n\n    opt := &godo.ListOptions{\n      PerPage: 10,\n      Page:    1,\n    }\n\n    client.Projects.ListResources(ctx, \"4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679\", opt)\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

          client = DropletKit::Client.new(access_token: token)


          client.projects.list_resources(id: ''4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679'')'
      - lang: Python
        source: 'import os

          from pydo import Client


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


          resp = client.projects.list_resources(project_id="4e1bfbc3")'
      security:
      - bearer_auth:
        - project:read
    post:
      operationId: projects_assign_resources
      summary: Assign Resources to a Project
      description: To assign resources to a project, send a POST request to `/v2/projects/$PROJECT_ID/resources`.
      tags:
      - Project Resources
      parameters:
      - $ref: '#/components/parameters/project_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/project_assignment'
            examples:
              assign_resources:
                value:
                  resources:
                  - do:droplet:13457723
                  - do:domain:example.com
      responses:
        '200':
          $ref: '#/components/responses/assigned_resources_list'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
        '500':
          $ref: '#/components/responses/server_error'
        default:
          $ref: '#/components/responses/unexpected_error'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"resources\": [\"do:droplet:1\", \"do:floatingip:192.168.99.100\"]}' \\\n  \"https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources\""
      - lang: Go
        source: "import (\n    \"context\"\n    \"os\"\n\n    \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n    token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n    client := godo.NewFromToken(token)\n    ctx := context.TODO()\n\n    res := []interface{}{\n      &godo.Droplet{ID: 1},\n      \"do:droplet:42\",\n      &godo.FloatingIP{IP: \"192.168.99.100\"},\n    }\n\n    client.Projects.AssignResources(ctx, \"4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679\", res...)\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

          client = DropletKit::Client.new(access_token: token)


          resource = DropletKit::ProjectAssignment.new(urn: ''do:droplet:1'')

          client.projects.assign_resources([resource], id: ''4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679'')'
      - lang: Python
        source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n  \"resources\": [\n    \"do:droplet:13457723\",\n    \"do:domain:example.com\"\n  ]\n}\n\nresp = client.projects.assign_resources(project_id=\"8dafda\", body=req)"
      security:
      - bearer_auth:
        - project:update
  /v2/projects/default/resources:
    get:
      operationId: projects_list_resources_default
      summary: List Default Project Resources
      description: To list all your resources in your default project, send a GET request to `/v2/projects/default/resources`.
      tags:
      - Project Resources
      responses:
        '200':
          $ref: '#/components/responses/resources_list'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
        '500':
          $ref: '#/components/responses/server_error'
        default:
          $ref: '#/components/responses/unexpected_error'
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  \"https://api.digitalocean.com/v2/projects/default/resources\""
      - lang: Go
        source: "import (\n    \"context\"\n    \"os\"\n\n    \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n    token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n    client := godo.NewFromToken(token)\n    ctx := context.TODO()\n\n    opt := &godo.ListOptions{\n      PerPage: 10,\n      Page:    1,\n    }\n\n    client.Projects.ListResources(ctx, godo.DefaultProject, opt)\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

          client = DropletKit::Client.new(access_token: token)


          client.projects.list_resources(id: ''default'')'
      - lang: Python
        source: 'import os

          from pydo import Client


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


          resp = client.projects.list_resources_default()'
      security:
      - bearer_auth:
        - project:read
    post:
      operationId: projects_assign_resources_default
      summary: Assign Resources to Default Project
      description: To assign resources to your default project, send a POST request to `/v2/projects/default/resources`.
      tags:
      - Project Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/project_assignment'
            examples:
              assign_resources:
                value:
                  resources:
                  - do:droplet:13457723
                  - do:domain:example.com
      responses:
        '200':
          $ref: '#/components/responses/assigned_resources_list'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
        '500':
          $ref: '#/components/responses/server_error'
        default:
          $ref: '#/components/responses/unexpected_error'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  -d '{\"resources\": [\"do:droplet:1\", \"do:floatingip:192.168.99.100\"]}' \\\n  \"https://api.digitalocean.com/v2/projects/default/resources\""
      - lang: Go
        source: "import (\n    \"context\"\n    \"os\"\n\n    \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n    token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n    client := godo.NewFromToken(token)\n    ctx := context.TODO()\n\n    res := []interface{}{\n      &godo.Droplet{ID: 1},\n      \"do:droplet:42\",\n      &godo.FloatingIP{IP: \"192.168.99.100\"},\n    }\n\n    client.Projects.AssignResources(ctx, godo.DefaultProject, res...)\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

          client = DropletKit::Client.new(access_token: token)


          resource = DropletKit::ProjectAssignment.new(urn: ''do:droplet:1'')

          client.projects.assign_resources([resource], id: ''default'')'
      - lang: Python
        source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n  \"resources\": [\n    \"do:droplet:13457723\",\n    \"do:domain:example.com\"\n  ]\n}\n\nresp = client.projects.assign_resources_default(body=req)"
      security:
      - bearer_auth:
        - project:update
components:
  schemas:
    meta_properties:
      type: object
      description: Information about the response itself.
      properties:
        total:
          description: Number of objects returned by the request.
          type: integer
          example: 1
    link_to_last_page:
      type: object
      properties:
        last:
          description: URI of the last page of the results.
          type: string
          example: https://api.digitalocean.com/v2/images?page=2
    error:
      type: object
      properties:
        id:
          description: 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."
          type: string
          example: not_found
        message:
          description: A message providing additional information about the error, including  details to help resolve it when possible.
          type: string
          example: The resource you were accessing could not be found.
        request_id:
          description: Optionally, some endpoints may include a request ID that should be  provided when reporting bugs or opening support tickets to help  identify the issue.
          type: string
          example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9
      required:
      - id
      - message
    backward_links:
      allOf:
      - $ref: '#/components/schemas/link_to_first_page'
      - $ref: '#/components/schemas/link_to_prev_page'
    urn:
      type: string
      pattern: ^do:(dbaas|domain|droplet|floatingip|loadbalancer|space|volume|kubernetes|vpc):.*
      example: do:droplet:13457723
      description: The uniform resource name (URN) for the resource in the format do:resource_type:resource_id.
    project_assignment:
      type: object
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/urn'
          example:
          - do:droplet:13457723
          description: A list of uniform resource names (URNs) to be added to a project.
    meta:
      type: object
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/meta_properties'
          - required:
            - total
      required:
      - meta
    link_to_next_page:
      type: object
      properties:
        next:
          description: URI of the next page of the results.
          type: string
          example: https://api.digitalocean.com/v2/images?page=2
    resource:
      type: object
      properties:
        urn:
          $ref: '#/components/schemas/urn'
        assigned_at:
          type: string
          format: date-time
          example: '2018-09-28T19:26:37Z'
          description: A time value given in ISO8601 combined date and time format that represents when the project was created.
        links:
          type: object
          description: The links object contains the `self` object, which contains the resource relationship.
          properties:
            self:
              type: string
              format: uri
              example: https://api.digitalocean.com/v2/droplets/13457723
              description: A URI that can be used to retrieve the resource.
        status:
          type: string
          enum:
          - ok
          - not_found
          - assigned
          - already_assigned
          - service_down
          example: ok
          description: The status of assigning and fetching the resources.
    pagination:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/page_links'
    link_to_prev_page:
      type: object
      properties:
        prev:
          description: URI of the previous page of the results.
          type: string
          example: https://api.digitalocean.com/v2/images?page=1
    link_to_first_page:
      type: object
      properties:
        first:
          description: URI of the first page of the results.
          type: string
          example: https://api.digitalocean.com/v2/images?page=1
    forward_links:
      allOf:
      - $ref: '#/components/schemas/link_to_last_page'
      - $ref: '#/components/schemas/link_to_next_page'
    page_links:
      type: object
      properties:
        pages:
          anyOf:
          - $ref: '#/components/schemas/forward_links'
          - $ref: '#/components/schemas/backward_links'
          - {}
          example:
            pages:
              first: https://api.digitalocean.com/v2/account/keys?page=1
              prev: https://api.digitalocean.com/v2/account/keys?page=2
  responses:
    unexpected_error:
      description: Unexpected error
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: example_error
            message: some error message
    assigned_resources_list:
      description: The response will be a JSON object with a key called `resources`. The value of this will be an object with the standard resource attributes.
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              resources:
                type: array
                items:
                  $ref: '#/components/schemas/resource'
            example:
              resources:
              - urn: do:droplet:13457723
                assigned_at: '2018-09-28T19:26:37Z'
                links:
                  self: https://api.digitalocean.com/v2/droplets/13457723
                status: ok
              - urn: do:domain:example.com
                assigned_at: '2019-03-31T16:24:14Z'
                links:
                  self: https://api.digitalocean.com/v2/domains/example.com
                status: ok
    not_found:
      description: The resource was not found.
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: not_found
            message: The resource you requested could not be found.
    too_many_requests:
      description: API Rate limit exceeded
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: too_many_requests
            message: API Rate limit exceeded.
    unauthorized:
      description: Unauthorized
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: unauthorized
            message: Unable to authenticate you.
    resources_list:
      description: The response will be a JSON object with a key called `resources`. The value of this will be an object with the standard resource attributes.
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            allOf:
            - type: object
              properties:
                resources:
                  type: array
                  items:
                    $ref: '#/components/schemas/resource'
            - $ref: '#/components/schemas/pagination'
            - $ref: '#/components/schemas/meta'
            example:
              resources:
              - urn: do:droplet:13457723
                assigned_at: '2018-09-28T19:26:37Z'
                links:
                  self: https://api.digitalocean.com/v2/droplets/13457723
                status: ok
              - urn: do:domain:example.com
                assigned_at: '2019-03-31T16:24:14Z'
                links:
                  self: https://api.digitalocean.com/v2/domains/example.com
                status: ok
              links:
                pages:
                  first: https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1
                  last: https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1
              meta:
                total: 2
    server_error:
      description: Server error.
      headers:
        ratelimit-limit:
          $ref: '#/components/headers/ratelimit-limit'
        ratelimit-remaining:
          $ref: '#/components/headers/ratelimit-remaining'
        ratelimit-reset:
          $ref: '#/components/headers/ratelimit-reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            id: server_error
            message: Unexpected server-side error
  parameters:
    project_id:
      in: path
      name: project_id
      description: A unique identifier for a project.
      required: true
      schema:
        type: string
        format: uuid
        minimum: 1
      example: 4de7ac8b-495b-4884-9a69-1050c6793cd6
    per_page:
      in: query
      name: per_page
      required: false
      description: Number of items returned per page
      schema:
        type: integer
        minimum: 1
        default: 20
        maximum: 200
      example: 2
    page:
      in: query
      name: page
      required: false
      description: Which 'page' of paginated results to return.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
  headers:
    ratelimit-reset:
      schema:
        type: integer
      example: 1444931833
      description: The time when the oldest request will expire. The value is given in Unix epoch time. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire.
    ratelimit-remaining:
      schema:
        type: integer
      example: 4816
      description: The number of requests in your hourly quota that remain before you hit your request limit. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire.
    ratelimit-limit:
      schema:
        type: integer
      example: 5000
      description: 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.
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: '## 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](https://cloud.digitalocean.com/account/api/tokens)

        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](https://docs.digitalocean.com/reference/api/oauth-api/)

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

        ```

        '