Linode Instances

Disks List

get
https://api.linode.com/v4/linode/instances/{linodeId}/disks

View Disk information for Disks associated with this Linode.

Path Parameters

linodeId
Required
integer

ID of the Linode to look up.

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 500]
Default: 100

The number of items to return per page.

Request Samples

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/linode/instances/123/disks

Response Samples

{
  "data": [
    {
      "id": "",
      "created": "2018-01-01T00:01:01",
      "status": "ready",
      "label": "Debian 9 Disk",
      "updated": "2018-01-01T00:01:01",
      "size": 48640,
      "filesystem": "ext4"
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Responses

200: Returns a paginated list of disks associated with this Linode.

data
array of objects
id
integer

This Disk's ID which must be provided for all operations impacting this Disk.

created
string

When this Disk was created.

status
string
Enum: "ready""not ready""deleting"

A brief description of this Disk's current state. This field may change without direct action from you, as a result of operations performed to the Disk or the Linode containing the Disk.

label
Filterable
string

The Disk's label is for display purposes only.

updated
string

When this Disk was last updated.

size
Filterable
integer

The size of the Disk in MB.

filesystem
string
Enum: "raw""swap""ext3""ext4""initrd"

The Disk filesystem can be one of:

  • raw - No filesystem, just a raw binary stream.
  • swap - Linux swap area.
  • ext3 - The ext3 journaling filesystem for Linux.
  • ext4 - The ext4 journaling filesystem for Linux.
  • initrd - initrd (uncompressed initrd, ext2, max 32 MB).
page
integer

The current page.

pages
integer

The total number of pages.

results
integer

The total number of results.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Disk Create

post
https://api.linode.com/v4/linode/instances/{linodeId}/disks

Adds a new Disk to a Linode.

  • You can optionally create a Disk from an Image or an Empty Disk if no Image is provided with a request.

  • When creating an Empty Disk, providing a label is required.

  • If no label is provided, an image is required instead.

  • When creating a Disk from an Image, root_pass is required.

  • The default filesystem for new Disks is ext4. If creating a Disk from an Image, the filesystem of the Image is used unless otherwise specified.

  • When deploying a StackScript on a Disk:

    • See StackScripts List (GET /linode/stackscripts) for a list of available StackScripts.
    • Requires a compatible Image to be supplied.
    • It is recommended to supply SSH keys for the root User using the authorized_keys field.
    • You may also supply a list of usernames via the authorized_users field.
      • These users must have an SSH Key associated with their Profiles first. See SSH Key Add (POST /profile/sshkeys) for more information.

Path Parameters

linodeId
Required
integer

ID of the Linode to look up.

Request Body Schema

size
Required
Filterable
integer

The size of the Disk in MB.

Images require a minimum size. Access the Image View (GET /images/{imageID}) endpoint to view its size.

authorized_keys
array

A list of public SSH keys that will be automatically appended to the root user's ~/.ssh/authorized_keys file when deploying from an Image.

authorized_users
array

A list of usernames. If the usernames have associated SSH keys, the keys will be appended to the root users ~/.ssh/authorized_keys file automatically when deploying from an Image.

filesystem
string

The Disk filesystem can be one of:

  • raw - No filesystem, just a raw binary stream.
  • swap - Linux swap area.
  • ext3 - The ext3 journaling filesystem for Linux.
  • ext4 - The ext4 journaling filesystem for Linux.
  • initrd - initrd (uncompressed initrd, ext2, max 32 MB).
image
string

An Image ID to deploy the Linode Disk from.

Access the Images List (GET /images) endpoint with authentication to view all available Images. Official Linode Images start with linode/, while your Account's Images start with private/. Creating a disk from a Private Image requires read_only or read_write permissions for that Image. Access the User's Grant Update (PUT /account/users/{username}/grants) endpoint to adjust permissions for an Account Image.

label
Filterable
string [1 .. 48] characters

The Disk's label is for display purposes only.

root_pass
string <password>[7 .. 128] characters

This sets the root user's password on a newly-created Linode Disk when deploying from an Image.

  • Required when creating a Linode Disk from an Image, including when using a StackScript.

  • Must meet a password strength score requirement that is calculated internally by the API. If the strength requirement is not met, you will receive a Password does not meet strength requirement error.

stackscript_data
object

This field is required only if the StackScript being deployed requires input data from the User for successful completion. See User Defined Fields (UDFs) for more details.

This field is required to be valid JSON.

Total length cannot exceed 65,535 characters.

stackscript_id
integer

A StackScript ID that will cause the referenced StackScript to be run during deployment of this Linode. A compatible image is required to use a StackScript. To get a list of available StackScript and their permitted Images see /stackscripts. This field cannot be used when deploying from a Backup or a Private Image.

Request Samples

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "label": "Debian 9 Disk",
      "image": "linode/debian9",
      "size": 1300,
      "authorized_keys": [
        "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
      ],
      "authorized_users": [
        "myUser",
        "secondaryUser"
      ],
      "root_pass": "aComplexP@ssword",
      "stackscript_id": 10079,
      "stackscript_data": {
        "gh_username": "linode"
      }
    }' \
    https://api.linode.com/v4/linode/instances/123/disks

Response Samples

{
  "status": "ready",
  "created": "2018-01-01T00:01:01",
  "updated": "2018-01-01T00:01:01",
  "id": 1234,
  "label": "Debian 9 Disk",
  "size": 48640,
  "filesystem": "ext4"
}

Responses

200: Disk created.

status
string
Enum: "ready""not ready""deleting"

A brief description of this Disk's current state. This field may change without direct action from you, as a result of operations performed to the Disk or the Linode containing the Disk.

created
string <date-time>

When this Disk was created.

updated
string <date-time>

When this Disk was last updated.

id
integer

This Disk's ID which must be provided for all operations impacting this Disk.

label
Filterable
string [1 .. 48] characters

The Disk's label is for display purposes only.

size
Filterable
integer

The size of the Disk in MB.

filesystem
string
Enum: "raw""swap""ext3""ext4""initrd"

The Disk filesystem can be one of:

  • raw - No filesystem, just a raw binary stream.
  • swap - Linux swap area.
  • ext3 - The ext3 journaling filesystem for Linux.
  • ext4 - The ext4 journaling filesystem for Linux.
  • initrd - initrd (uncompressed initrd, ext2, max 32 MB).

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.