Digital Ocean Actions API

openapi: 3.2.0
info:
  title: DigitalOcean Actions 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: Actions
  description: Actions are records of events that have occurred on the resources in your account.
paths:
  /v2/actions:
    get:
      operationId: actions_list
      summary: List All Actions
      description: This will be the entire list of actions taken on your account, so it will be quite large. As with any large collection returned by the API, the results will be paginated with only 20 on each page by default.
      tags:
      - Actions
      parameters:
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          $ref: '#/components/responses/actions'
        '401':
          $ref: '#/components/responses/unauthorized'
        '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/actions?page=1&per_page=1\""
      - 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      Page:    1,\n      PerPage: 200,\n  }\n  actions, _, err := client.Actions.List(ctx, opt)\n  }"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

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


          actions = client.actions.all

          actions.each'
      - lang: Python
        source: 'import os

          from pydo import Client


          client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN"))


          list_resp = client.actions.list()'
      security:
      - bearer_auth:
        - actions:read
  /v2/actions/{action_id}:
    get:
      operationId: actions_get
      summary: Retrieve an Existing Action
      description: To retrieve a specific action object, send a GET request to `/v2/actions/$ACTION_ID`.
      tags:
      - Actions
      parameters:
      - $ref: '#/components/parameters/action_id'
      responses:
        '200':
          $ref: '#/components/responses/action'
        '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/actions/36804636\""
      - 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    action, _, err := client.Actions.Get(ctx, 36804636)\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

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


          client.actions.find(id: 36804636)'
      - lang: Python
        source: 'import os

          from pydo import Client


          client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN"))


          get_resp = client.actions.get(action_id=36804636)'
      security:
      - bearer_auth:
        - actions:read
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
    region:
      type: object
      properties:
        name:
          type: string
          description: The display name of the region.  This will be a full name that is used in the control panel and other interfaces.
          example: New York 3
        slug:
          type: string
          description: A human-readable string that is used as a unique identifier for each region.
          example: nyc3
        features:
          items:
            type: string
          description: This attribute is set to an array which contains features available in this region
          example:
          - private_networking
          - backups
          - ipv6
          - metadata
          - install_agent
          - storage
          - image_transfer
        available:
          type: boolean
          description: This is a boolean value that represents whether new Droplets can be created in this region.
          example: true
        sizes:
          items:
            type: string
          description: This attribute is set to an array which contains the identifying slugs for the sizes available in this region.
          example:
          - s-1vcpu-1gb
          - s-1vcpu-2gb
          - s-1vcpu-3gb
          - s-2vcpu-2gb
          - s-3vcpu-1gb
          - s-2vcpu-4gb
          - s-4vcpu-8gb
          - s-6vcpu-16gb
          - s-8vcpu-32gb
          - s-12vcpu-48gb
          - s-16vcpu-64gb
          - s-20vcpu-96gb
          - s-24vcpu-128gb
          - s-32vcpu-192g
      required:
      - available
      - features
      - name
      - sizes
      - slug
    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'
    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
    action:
      type: object
      properties:
        id:
          type: integer
          description: A unique numeric ID that can be used to identify and reference an action.
          example: 36804636
        status:
          type: string
          description: The current status of the action. This can be "in-progress", "completed", or "errored".
          enum:
          - in-progress
          - completed
          - errored
          example: completed
          default: in-progress
        type:
          type: string
          description: This is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action.
          example: create
        started_at:
          type: string
          format: date-time
          description: A time value given in ISO8601 combined date and time format that represents when the action was initiated.
          example: '2020-11-14T16:29:21Z'
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: A time value given in ISO8601 combined date and time format that represents when the action was completed.
          example: '2020-11-14T16:30:06Z'
        resource_id:
          type:
          - integer
          - 'null'
          description: A unique identifier for the resource that the action is associated with.
          example: 3164444
        resource_type:
          type: string
          description: The type of resource that the action is associated with.
          example: droplet
        region:
          $ref: '#/components/schemas/region'
        region_slug:
          type:
          - string
          - 'null'
          description: A human-readable string that is used as a unique identifier for each region.
          example: nyc3
    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
    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.
    actions:
      description: The results will be returned as a JSON object with an actions key.  This will be set to an array filled with action objects containing the standard action 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:
                actions:
                  type: array
                  items:
                    $ref: '#/components/schemas/action'
            - $ref: '#/components/schemas/pagination'
            - $ref: '#/components/schemas/meta'
    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.
    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
    action:
      description: The result will be a JSON object with an action key.  This will be set to an action object containing the standard action 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:
            properties:
              action:
                $ref: '#/components/schemas/action'
  parameters:
    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
    action_id:
      in: path
      name: action_id
      description: A unique numeric ID that can be used to identify and reference an action.
      required: true
      schema:
        type: integer
        minimum: 1
      example: 36804636
    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"

        ```

        '