Linode Instances v4.78.3

Linodes List

GET https://api.linode.com/v4/linode/instances

Returns a paginated list of Linodes you have permission to view.

Authorizations

personalAccessToken
oauth linodes:read_only

Query Parameters

page
Type:
integer >= 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Linode Create

POST https://api.linode.com/v4/linode/instances

Creates a Linode Instance on your Account. In order for this request to complete successfully, your User must have the add_linodes grant. Creating a new Linode will incur a charge on your Account.

Linodes can be created using one of the available Types. See GET /linode/types to get more information about each Type’s specs and cost.

Linodes can be created in any one of our available Regions for a list of available Regions you can deploy your Linode in.

In an effort to fight spam, Linode restricts outbound connections on ports 25, 465, and 587 on all Linodes for new accounts created after November 5th, 2019. For more information, see Sending Email on Linode.

Linodes can be created in a number of ways:

  • Using a Linode Linux Distribution image or an Image you created based on another Linode.

    • The Linode will be running after it completes provisioning.
    • A default config with two Disks, one being a 512 swap disk, is created.
      • swap_size can be used to customize the swap disk size.
    • Requires a root_pass be supplied to use for the root User’s Account.
    • 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 your Profile first. See /profile/sshkeys for more information.
  • Using a StackScript.

    • See /linode/stackscripts for a list of available StackScripts.
    • The Linode will be running after it completes provisioning.
    • Requires a compatible Image to be supplied.
    • Requires a root_pass be supplied to use for the root User’s Account.
    • 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 your Profile first. See /profile/sshkeys for more information.
  • Using one of your other Linode’s backups.

    • You must create a Linode large enough to accommodate the Backup’s size.
    • The Disks and Config will match that of the Linode that was backed up.
    • The root_pass will match that of the Linode that was backed up.
  • Create an empty Linode.

    • The Linode will remain offline and must be manually started.
    • Disks and Configs must be created manually.
    • This is only recommended for advanced use cases.

Important: You must be an unrestricted User in order to add or modify tags on Linodes.

Authorizations

personalAccessToken
oauth linodes:read_write

Request Body Schema

authorized_keys
array

A list of SSH public keys to deploy for the root user on the newly-created Linode. Only accepted if image is provided.

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.

backup_id
integer

A Backup ID from another Linode’s available backups. Your User must have read_write access to that Linode, the Backup must have a status of successful, and the Linode must be deployed to the same region as the Backup. See /linode/instances/{linodeId}/backups for a Linode’s available backups.

This field and the image field are mutually exclusive.

backups_enabled
boolean

If this field is set to true, the created Linode will automatically be enrolled in the Linode Backup service. This will incur an additional charge. The cost for the Backup service is dependent on the Type of Linode deployed.

This option is always treated as true if the account-wide backups_enabled setting is true. See account settings for more information.

Backup pricing is included in the response from /linodes/types

booted
boolean

Whether to boot this Linode after the deploy is complete. Defaults to true if image is provided. Not accepted if not deploying from an Image.

group
Filterable
string

A deprecated property denoting a group label for this Linode.

image
string

An Image ID to deploy the Disk from. Official Linode Images start with linode/ , while your Images start with private/. See /images for more information on the Images available for you to use.

label
Filterable

The Linode’s label is for display purposes only. If no label is provided for a Linode, a default will be assigned. Linode labels have the following constraints:

  • Must start with an alpha character.
  • May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
  • Cannot have two dashes (--), underscores (__) or periods (..) in a row.

private_ip
boolean

If true, the created Linode will have private networking enabled.

region
Required
string

The Region where the Linode will be located.

root_pass
string <password>

This will set the root user’s password on the newly-created Linode. Linode passwords have the following constraints:

  • 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

An object containing responses to any User Defined Fields present in the StackScript being deployed to this Linode. Only accepted if stackscript_id is given. The required values depend on the StackScript being deployed.

stackscript_id
integer

The StackScript to deploy to the newly-created Linode. If provided, “image” must also be provided, and must be an Image that is compatible with this StackScript.

swap_size
integer

When deploying from an Image, this field is optional, otherwise it is ignored. This is used to set the swap disk size for the newly-created Linode.

tags
Filterable
array

An array of tags applied to this object. Tags are for organizational purposes only.

type
Required
string

The Linode Type of the Linode you are creating.

Request Samples

Response Samples

Responses

Linode Delete

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

Deletes a Linode you have permission to read_write.

Deleting a Linode is a destructive action and cannot be undone.

Additionally, deleting a Linode:

  • Gives up any IP addresses the Linode was assigned.
  • Deletes all Disks, Backups, Configs, etc.
  • Stops billing for the Linode and its associated services. You will be billed for time used within the billing period the Linode was active.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up

Request Samples

Response Samples

Responses

Linode View

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

Get a specific Linode by ID.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up

Request Samples

Response Samples

Responses

Linode Update

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

Updates a Linode that you have permission to read_write.

Important: You must be an unrestricted User in order to add or modify tags on Linodes.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up

Request Body Schema

alerts
object
cpu
integer

The percentage of CPU usage required to trigger an alert. If the average CPU usage over two hours exceeds this value, we’ll send you an alert. Your Linode’s total CPU capacity is represented as 100%, multiplied by its number of cores.

For example, a two core Linode’s CPU capacity is represented as 200%. If you want to be alerted at 90% of a two core Linode’s CPU capacity, set the alert value to 180.

The default value is 90% multiplied by the number of cores.

If the value is set to 0 (zero), the alert is disabled.

io
integer

The amount of disk IO operation per second required to trigger an alert. If the average disk IO over two hours exceeds this value, we’ll send you an alert. If set to 0 (zero), this alert is disabled.

network_in
integer

The amount of incoming traffic, in Mbit/s, required to trigger an alert. If the average incoming traffic over two hours exceeds this value, we’ll send you an alert. If this is set to 0 (zero), the alert is disabled.

network_out
integer

The amount of outbound traffic, in Mbit/s, required to trigger an alert. If the average outbound traffic over two hours exceeds this value, we’ll send you an alert. If this is set to 0 (zero), the alert is disabled.

transfer_quota
integer

The percentage of network transfer that may be used before an alert is triggered. When this value is exceeded, we’ll alert you. If this is set to 0 (zero), the alert is disabled.

backups
object

Information about this Linode’s backups status. For information about available backups, see /linode/instances/{linodeId}/backups.

schedule
object
day
Nullable
string
Enum: Scheduling Sunday Monday Tuesday Wednesday Thursday Friday Saturday

The day of the week that your Linode’s weekly Backup is taken. If not set manually, a day will be chosen for you. Backups are taken every day, but backups taken on this day are preferred when selecting backups to retain for a longer period.

If not set manually, then when backups are initially enabled, this may come back as Scheduling until the day is automatically selected.

window
Nullable
string
Enum: Scheduling W0 W2 W4 W6 W8 W10 W12 W14 W16 W18 W20 W22

The window in which your backups will be taken, in UTC. A backups window is a two-hour span of time in which the backup may occur.

For example, W10 indicates that your backups should be taken between 10:00 and 12:00. If you do not choose a backup window, one will be selected for you automatically.

If not set manually, when backups are initially enabled this may come back as Scheduling until the window is automatically selected.

group
Filterable
string

A deprecated property denoting a group label for this Linode.

label
Filterable
string 3..32 characters

The Linode’s label is for display purposes only. If no label is provided for a Linode, a default will be assigned. Linode labels have the following constraints:

  • Must start with an alpha character.
  • May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
  • Cannot have two dashes (--), underscores (__) or periods (..) in a row.

tags
Filterable
array

An array of tags applied to this object. Tags are for organizational purposes only.

watchdog_enabled
boolean

The watchdog, named Lassie, is a Shutdown Watchdog that monitors your Linode and will reboot it if it powers off unexpectedly. It works by issuing a boot job when your Linode powers off without a shutdown job being responsible. To prevent a loop, Lassie will give up if there have been more than 5 boot jobs issued within 15 minutes.

Request Samples

Response Samples

Responses

Backups List

GET https://api.linode.com/v4/linode/instances/{linodeId}/backups

Returns information about this Linode’s available backups.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

The ID of the Linode the backups belong to.

Request Samples

Response Samples

Responses

Snapshot Create

POST https://api.linode.com/v4/linode/instances/{linodeId}/backups

Creates a snapshot Backup of a Linode. ** If you already have a snapshot of this Linode, this is a destructive action. The previous snapshot will be deleted.**

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode the backups belong to.

Request Body Schema

label
Required
string 1..255 characters

Request Samples

Response Samples

Responses

Backups Cancel

POST https://api.linode.com/v4/linode/instances/{linodeId}/backups/cancel

Cancels the Backup service on the given Linode. Deletes all of this Linode’s existing backups forever.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode to cancel backup service for.

Request Samples

Response Samples

Responses

Backups Enable

POST https://api.linode.com/v4/linode/instances/{linodeId}/backups/enable

Enables backups for the specified Linode.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode to enable backup service for.

Request Samples

Response Samples

Responses

Backup View

GET https://api.linode.com/v4/linode/instances/{linodeId}/backups/{backupId}

Returns information about a Backup.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

The ID of the Linode the Backup belongs to.

backupId integer Required

The ID of the Backup to look up.

Request Samples

Response Samples

Responses

Backup Restore

POST https://api.linode.com/v4/linode/instances/{linodeId}/backups/{backupId}/restore

Restores a Linode’s Backup to the specified Linode.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode that the Backup belongs to.

backupId integer Required

The ID of the Backup to restore.

Request Body Schema

linode_id
Required
integer

The ID of the Linode to restore a Backup to.

overwrite
boolean

If True, deletes all Disks and Configs on the target Linode before restoring.

If False, and the Disk image size is larger than the available space on the Linode, an error message indicating insufficient space is returned.

Request Samples

Response Samples

Responses

Linode Boot

POST https://api.linode.com/v4/linode/instances/{linodeId}/boot

Boots a Linode you have permission to modify. If no parameters are given, a Config profile will be chosen for this boot based on the following criteria:

  • If there is only one Config profile for this Linode, it will be used.
  • If there is more than one Config profile, the last booted config will be used.
  • If there is more than one Config profile and none were the last to be booted (because the Linode was never booted or the last booted config was deleted) an error will be returned.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode to boot.

Request Body Schema

config_id
integer

The Linode Config ID to boot into. If omitted, we will attempt to select a config to use. (This will do the right thing in most cases.)

Request Samples

Response Samples

Responses

Linode Clone

POST https://api.linode.com/v4/linode/instances/{linodeId}/clone

You can clone your Linode’s existing Disks or Configuration profiles to another Linode on your Account. In order for this request to complete successfully, your User must have the add_linodes grant. Cloning to a new Linode will incur a charge on your Account.

If cloning to an existing Linode, any actions currently running or queued must be completed first before you can clone to it.

Up to five clone operations from any given source Linode can be run concurrently. If more concurrent clones are attempted, an HTTP 400 error will be returned by this endpoint.

Any tags existing on the source Linode will be cloned to the target Linode.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to clone.

Request Body Schema

backups_enabled
boolean

If this field is set to true, the created Linode will automatically be enrolled in the Linode Backup service. This will incur an additional charge. Pricing is included in the response from /linodes/types.

  • Can only be included when cloning to a new Linode.

configs
array

An array of configuration profile IDs.

  • If the configs parameter is not provided, then all configuration profiles and their associated disks will be cloned from the source Linode. Any disks specified by the disks parameter will also be cloned.
  • If an empty array is provided for the configs parameter, then no configuration profiles (nor their associated disks) will be cloned from the source Linode. Any disks specified by the disks parameter will still be cloned.
  • If a non-empty array is provided for the configs parameter, then the configuration profiles specified in the array (and their associated disks) will be cloned from the source Linode. Any disks specified by the disks parameter will also be cloned.

disks
array

An array of disk IDs.

  • If the disks parameter is not provided, then no extra disks will be cloned from the source Linode. All disks associated with the configuration profiles specified by the configs parameter will still be cloned.
  • If an empty array is provided for the disks parameter, then no extra disks will be cloned from the source Linode. All disks associated with the configuration profiles specified by the configs parameter will still be cloned.
  • If a non-empty array is provided for the disks parameter, then the disks specified in the array will be cloned from the source Linode, in addition to any disks associated with the configuration profiles specified by the configs parameter.

group
string

A label used to group Linodes for display. Linodes are not required to have a group.

label
string

The label to assign this Linode when cloning to a new Linode.

  • Can only be provided when cloning to a new Linode. * Defaults to “linode”.

linode_id
integer

If an existing Linode is to be the target for the clone, the ID of that Linode. The existing Linode must have enough resources to accept the clone.

region
Required
string

This is the Region where the Linode will be deployed. To view all available Regions you can deploy to see /regions.

  • Region can only be provided when cloning to a new Linode.

type
Required
string

A Linode’s Type determines what resources are available to it, including disk space, memory, and virtual cpus. The amounts available to a specific Linode are returned as specs on the Linode object.

To view all available Linode Types you can deploy with see /linode/types.

  • Type can only be provided when cloning to a new Linode.

Request Samples

Response Samples

Responses

Configuration Profiles List

GET https://api.linode.com/v4/linode/instances/{linodeId}/configs

Lists Configuration profiles associated with a Linode.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up Configuration profiles for.

Query Parameters

page
Type:
integer >= 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Configuration Profile Create

POST https://api.linode.com/v4/linode/instances/{linodeId}/configs

Adds a new Configuration profile to a Linode.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up Configuration profiles for.

Request Body Schema

comments
Nullable
string

Optional field for arbitrary User comments on this Config.

devices
Required
object

A dictionary of device disks to use as a device map in a Linode’s configuration profile.

  • An empty device disk dictionary or a dictionary with empty values for device slots is allowed.
  • If no devices are specified, booting from this configuration will hold waiting for a device to exist before being able to boot.

sda
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdb
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdc
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdd
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sde
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdf
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdg
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdh
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

helpers
object

Helpers enabled when booting to this Linode Config.

devtmpfs_automount
boolean

Populates the /dev directory early during boot without udev. Defaults to false.

distro
boolean

Helps maintain correct inittab/upstart console device.

modules_dep
boolean

Creates a modules dependency file for the Kernel you run.

network
boolean

Automatically configures static networking.

updatedb_disabled
boolean

Disables updatedb cron job to avoid disk thrashing.

kernel
string

A Kernel ID to boot a Linode with. Defaults to “linode/latest-64bit”.

label
Filterable
Required
string 1..48 characters

The Config’s label is for display purposes only.

memory_limit
integer

Defaults to the total RAM of the Linode.

root_device
string

The root device to boot.

  • If no value or an invalid value is provided, root device will default to /dev/sda.
  • If the device specified at the root device location is not mounted, the Linode will not boot until a device is mounted.

run_level
string
Enum: default single binbash

Defines the state of your Linode after booting. Defaults to default.

virt_mode
string
Enum: paravirt fullvirt

Controls the virtualization mode. Defaults to paravirt.

  • paravirt is suitable for most cases. Linodes running in paravirt mode share some qualities with the host, ultimately making it run faster since there is less transition between it and the host.
  • full_virt affords more customization, but is slower because 100% of the VM is virtualized.

Request Samples

Response Samples

Responses

Configuration Profile Delete

DELETE https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}

Deletes the specified Configuration profile from the specified Linode.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode whose Configuration profile to look up.

configId integer Required

The ID of the Configuration profile to look up.

Request Samples

Response Samples

Responses

Configuration Profile View

GET https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}

Returns information about a specific Configuration profile.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

The ID of the Linode whose Configuration profile to look up.

configId integer Required

The ID of the Configuration profile to look up.

Request Samples

Response Samples

Responses

Configuration Profile Update

PUT https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}

Updates a Configuration profile.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode whose Configuration profile to look up.

configId integer Required

The ID of the Configuration profile to look up.

Request Body Schema

comments
Nullable
string

Optional field for arbitrary User comments on this Config.

devices
Required
object

A dictionary of device disks to use as a device map in a Linode’s configuration profile.

  • An empty device disk dictionary or a dictionary with empty values for device slots is allowed. If no devices are specified, booting from this configuration will hold waiting for a device to exist before being able to boot.

    Note: An empty device disk dictionary or a dictionary with empty values for device slots previously errored in all cases.

sda
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdb
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdc
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdd
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sde
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdf
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdg
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdh
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

helpers
object

Helpers enabled when booting to this Linode Config.

devtmpfs_automount
boolean

Populates the /dev directory early during boot without udev. Defaults to false.

distro
boolean

Helps maintain correct inittab/upstart console device.

modules_dep
boolean

Creates a modules dependency file for the Kernel you run.

network
boolean

Automatically configures static networking.

updatedb_disabled
boolean

Disables updatedb cron job to avoid disk thrashing.

kernel
string

A Kernel ID to boot a Linode with. Defaults to “linode/latest-64bit”.

label
Filterable
Required
string 1..48 characters

The Config’s label is for display purposes only.

memory_limit
integer

Defaults to the total RAM of the Linode.

root_device
string

The root device to boot.

  • If no value or an invalid value is provided, root device will default to /dev/sda.

    Note: Previous validation errored when no value was provided for root device and an empty device map existed for the Linode’s configuration profile.
  • If the device specified at the root device location is not mounted, the Linode will not boot until a device is mounted.

run_level
string
Enum: default single binbash

Defines the state of your Linode after booting. Defaults to default.

virt_mode
string
Enum: paravirt fullvirt

Controls the virtualization mode. Defaults to paravirt.

  • paravirt is suitable for most cases. Linodes running in paravirt mode share some qualities with the host, ultimately making it run faster since there is less transition between it and the host.
  • full_virt affords more customization, but is slower because 100% of the VM is virtualized.

Request Samples

Response Samples

Responses

Disks List

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

View Disk information for Disks associated with this Linode.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Query Parameters

page
Type:
integer >= 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

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 (see /images for a list of available public images, or use one of your own), and optionally provide a StackScript to deploy with this Disk.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Request Body Schema

authorized_keys
array

A list of public SSH keys that will be automatically appended to the root user’s ~/.ssh/authorized_keys file.

authorized_users
array

A list of usernames that will have their SSH keys, if any, automatically appended to the root user’s ~/.ssh/authorized_keys file.

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

image
string

An Image ID to deploy the Disk from. Official Linode Images start with linode/ , while your Images start with private/. See /images for more information on the Images available for you to use.

label
Filterable
Required
string 1..48 characters

The Disk’s label is for display purposes only.

read_only
boolean

If true, this Disk is read-only.

root_pass
string <password>

This will set the root user’s password on the newly-created Linode. Linode passwords have the following constraints:

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

size
Filterable
Required
integer
stackscript_data
object

This field is required only if the StackScript being deployed requires input data from the User for successful completion. See Variables and UDFs for more details. This field is required to be valid JSON.

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

Response Samples

Responses

Disk Delete

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

Deletes a Disk you have permission to read_write.

Deleting a Disk is a destructive action and cannot be undone.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

diskId integer Required

ID of the Disk to look up.

Request Samples

Response Samples

Responses

Disk View

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

View Disk information for a Disk associated with this Linode.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

diskId integer Required

ID of the Disk to look up.

Request Samples

Response Samples

Responses

Disk Update

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

Updates a Disk that you have permission to read_write.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

diskId integer Required

ID of the Disk to look up.

Request Body Schema

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

label
Filterable
string 1..48 characters

The Disk’s label is for display purposes only.

Request Samples

Response Samples

Responses

Disk Clone

POST https://api.linode.com/v4/linode/instances/{linodeId}/disks/{diskId}/clone

Copies a disk, byte-for-byte, into a new Disk belonging to the same Linode. The Linode must have enough storage space available to accept a new Disk of the same size as this one or this operation will fail.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

diskId integer Required

ID of the Disk to clone.

Response Samples

Responses

Disk Root Password Reset

POST https://api.linode.com/v4/linode/instances/{linodeId}/disks/{diskId}/password

Resets the password of a Disk you have permission to read_write.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

diskId integer Required

ID of the Disk to look up.

Request Body Schema

password
Required
string

The new root password for the OS installed on this Disk. The password must meet the complexity strength validation requirements for a strong password.

Request Samples

Response Samples

Responses

Disk Resize

POST https://api.linode.com/v4/linode/instances/{linodeId}/disks/{diskId}/resize

Resizes a Disk you have permission to read_write. The Linode this Disk is attached to must be shut down for resizing to take effect. If you are resizing the Disk to a smaller size, it cannot be made smaller than what is required by the total size of the files current on the Disk. The Disk must not be in use. If the Disk is in use, the request will succeed but the resize will ultimately fail.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

diskId integer Required

ID of the Disk to look up.

Request Body Schema

size
integer >= 1

The desired size, in MB, of the disk.

Request Samples

Response Samples

Responses

Networking Information List

GET https://api.linode.com/v4/linode/instances/{linodeId}/ips

Returns networking information for a single Linode.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Request Samples

Response Samples

Responses

IPv4 Address Allocate

POST https://api.linode.com/v4/linode/instances/{linodeId}/ips

Allocates a public or private IPv4 address to a Linode. Public IP Addresses, after the one included with each Linode, incur an additional monthly charge. If you need an additional public IP Address you must request one - please open a support ticket. You may not add more than one private IPv4 address to a single Linode.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Request Body Schema

public
Required
boolean

Whether to create a public or private IPv4 address.

type
Required
string
Enum: ipv4

The type of address you are allocating. Only IPv4 addresses may be allocated through this endpoint.

Request Samples

Response Samples

Responses

IPv4 Address Delete

DELETE https://api.linode.com/v4/linode/instances/{linodeId}/ips/{address}

Deletes a public IPv4 address associated with this Linode. This will fail if it is the Linode’s last remaining public IPv4 address. Private IPv4 addresses cannot be removed via this endpoint.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode to look up.

address string <ip> Required

The IP address to look up.

Request Samples

Response Samples

Responses

IP Address View

GET https://api.linode.com/v4/linode/instances/{linodeId}/ips/{address}

View information about the specified IP address associated with the specified Linode.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

The ID of the Linode to look up.

address string <ip> Required

The IP address to look up.

Request Samples

Response Samples

Responses

IP Address Update

PUT https://api.linode.com/v4/linode/instances/{linodeId}/ips/{address}

Updates a particular IP Address associated with this Linode. Only allows setting/resetting reverse DNS.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

The ID of the Linode to look up.

address string <ip> Required

The IP address to look up.

Request Body Schema

rdns
string

The reverse DNS assigned to this address. For public IPv4 addresses, this will be set to a default value provided by Linode if not explicitly set.

Request Samples

Response Samples

Responses

DC Migration/Pending Host Migration Initiate

POST https://api.linode.com/v4/linode/instances/{linodeId}/migrate

Initiate a pending host migration that has been scheduled by Linode or initiate a cross data center (DC) migration. A list of pending migrations, if any, can be accessed from GET /account/notifications. When the migration begins, your Linode will be shutdown if not already off. If the migration initiated the shutdown, it will reboot the Linode when completed.

To initiate a cross DC migration, you must pass a region parameter to the request body specifying the target data center region. You can view a list of all available regions and their feature capabilities from GET /regions. If your Linode has a DC migration already queued or you have initiated a previously scheduled migration, you will not be able to initiate a DC migration until it has completed.

Note: Next Generation Network (NGN) data centers do not support IPv6 /116 pools or IP Failover. If you have these features enabled on your Linode and attempt to migrate to an NGN data center, the migration will not initiate. If a Linode cannot be migrated because of an incompatibility, you will be prompted to select a different data center or contact support.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to migrate.

Request Body Schema

region
string

The region to which the Linode will be migrated. Must be a valid region slug. A list of regions can be viewed by using the GET /regions endpoint. A cross data center migration will cancel a pending migration that has not yet been initiated. A cross data center migration will initiate a linode_migrate_datacenter_create event.

upgrade
boolean

When initiating a cross DC migration, setting this value to true will also ensure that the Linode is upgraded to the latest generation of hardware that corresponds to your Linode’s Type, if any free upgrades are available for it. If no free upgrades are available, and this value is set to true, then the endpoint will return a 400 error code and the migration will not be performed. If the data center set in the region field does not allow upgrades, then the endpoint will return a 400 error code and the migration will not be performed.

Request Samples

Response Samples

Responses

Linode Upgrade

POST https://api.linode.com/v4/linode/instances/{linodeId}/mutate

Linodes created with now-deprecated Types are entitled to a free upgrade to the next generation. A mutating Linode will be allocated any new resources the upgraded Type provides, and will be subsequently restarted if it was currently running. If any actions are currently running or queued, those actions must be completed first before you can initiate a mutate.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to mutate.

Request Body Schema

allow_auto_disk_resize
boolean

Automatically resize disks when resizing a Linode. When resizing down to a smaller plan your Linode’s data must fit within the smaller disk size.

Request Samples

Response Samples

Responses

Linode Root Password Reset

POST https://api.linode.com/v4/linode/instances/{linodeId}/password

Resets the root password for this Linode.

  • Your Linode must be shut down for a password reset to complete.
  • If your Linode has more than one disk (not counting its swap disk), use the Reset Disk Root Password endpoint to update a specific disk’s root password.
  • A password_reset event is generated when a root password reset is successful.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode for which to reset its root password.

Request Body Schema

root_pass
Required
string

The root user’s password on this Linode. Linode passwords 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.

Request Samples

Response Samples

Responses

Linode Reboot

POST https://api.linode.com/v4/linode/instances/{linodeId}/reboot

Reboots a Linode you have permission to modify. If any actions are currently running or queued, those actions must be completed first before you can initiate a reboot.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the linode to reboot.

Request Body Schema

config_id
integer

The Linode Config ID to reboot into. If null or omitted, the last booted config will be used. If there was no last booted config and this Linode only has one config, it will be used. If a config cannot be determined, an error will be returned.

Request Samples

Response Samples

Responses

Linode Rebuild

POST https://api.linode.com/v4/linode/instances/{linodeId}/rebuild

Rebuilds a Linode you have the read_write permission to modify. A rebuild will first shut down the Linode, delete all disks and configs on the Linode, and then deploy a new image to the Linode with the given attributes. Additionally:

  • Requires an image be supplied.
  • Requires a root_pass be supplied to use for the root User’s Account.
  • It is recommended to supply SSH keys for the root User using the authorized_keys field.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to rebuild.

Request Body Schema

authorized_keys
array

A list of public SSH keys that will be automatically appended to the root user’s ~/.ssh/authorized_keys file.

authorized_users
array

A list of usernames that will have their SSH keys, if any, automatically appended to the root user’s ~/.ssh/authorized_keys file.

booted
boolean

This field defaults to true if the Linode is created with an Image or from a Backup. If it is deployed from an Image or a Backup and you wish it to remain offline after deployment, set this to false.

image
Required
string

An Image ID to deploy the Disk from. Official Linode Images start with linode/ , while your Images start with private/. See /images for more information on the Images available for you to use.

root_pass
Required
string <password>

This will set the root user’s password on the newly-created Linode. Linode passwords have the following constraints:

  • 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 Variables and UDFs for more details. This field is required to be valid JSON.

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

Response Samples

Responses

Linode Boot into Rescue Mode

POST https://api.linode.com/v4/linode/instances/{linodeId}/rescue

Rescue Mode is a safe environment for performing many system recovery and disk management tasks. Rescue Mode is based on the Finnix recovery distribution, a self-contained and bootable Linux distribution. You can also use Rescue Mode for tasks other than disaster recovery, such as formatting disks to use different filesystems, copying data between disks, and downloading files from a disk via SSH and SFTP.

  • Note that “sdh” is reserved and unavailable during rescue.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to rescue.

Request Body Schema

devices
object
sda
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdb
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdc
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdd
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sde
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdf
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

sdg
object

Device can be either a Disk or Volume identified by disk_id or volume_id. Only one type per slot allowed. Can be null. Devices mapped from sde through sdh are unavailable in fullvirt virt_mode.

disk_id
integer

The Disk ID, or null if a Volume is assigned to this slot.

volume_id
integer

The Volume ID, or null if a Disk is assigned to this slot.

Request Samples

Response Samples

Responses

Linode Resize

POST https://api.linode.com/v4/linode/instances/{linodeId}/resize

Resizes a Linode you have the read_write permission to a different Type. If any actions are currently running or queued, those actions must be completed first before you can initiate a resize. Additionally, the following criteria must be met in order to resize a Linode:

  • The Linode must not have a pending migration.
  • Your Account cannot have an outstanding balance.
  • The Linode must not have more disk allocation than the new Type allows.
    • In that situation, you must first delete or resize the disk to be smaller.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to resize.

Request Body Schema

allow_auto_disk_resize
boolean

Automatically resize disks when resizing a Linode. When resizing down to a smaller plan your Linode’s data must fit within the smaller disk size.

type
Required
string

The ID representing the Linode Type.

Request Samples

Response Samples

Responses

Linode Shut Down

POST https://api.linode.com/v4/linode/instances/{linodeId}/shutdown

Shuts down a Linode you have permission to modify. If any actions are currently running or queued, those actions must be completed first before you can initiate a shutdown.

Authorizations

personalAccessToken
oauth linodes:read_write

Path Parameters

linodeId integer Required

ID of the Linode to shutdown.

Request Samples

Response Samples

Responses

Linode Statistics View

GET https://api.linode.com/v4/linode/instances/{linodeId}/stats

Returns CPU, IO, IPv4, and IPv6 statistics for your Linode for the past 24 hours.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Request Samples

Response Samples

Responses

Statistics View (year/month)

GET https://api.linode.com/v4/linode/instances/{linodeId}/stats/{year}/{month}

Returns statistics for a specific month. The year/month values must be either a date in the past, or the current month. If the current month, statistics will be retrieved for the past 30 days.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

year integer Required

Numeric value representing the year to look up.

month integer 1..12 Required

Numeric value representing the month to look up.

Request Samples

Response Samples

Responses

Network Transfer View

GET https://api.linode.com/v4/linode/instances/{linodeId}/transfer

Returns a Linode’s network transfer pool statistics for the current month.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Request Samples

Response Samples

Responses

Network Transfer View (year/month)

GET https://api.linode.com/v4/linode/instances/{linodeId}/transfer/{year}/{month}

Returns a Linode’s network transfer statistics for a specific month. The year/month values must be either a date in the past, or the current month.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

year integer 2000..2037 Required

Numeric value representing the year to look up.

month integer 1..12 Required

Numeric value representing the month to look up.

Request Samples

Response Samples

Responses

Linode's Volumes List

GET https://api.linode.com/v4/linode/instances/{linodeId}/volumes

View Block Storage Volumes attached to this Linode.

Authorizations

personalAccessToken
oauth linodes:read_only

Path Parameters

linodeId integer Required

ID of the Linode to look up.

Query Parameters

page
Type:
integer >= 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Kernels List

GET https://api.linode.com/v4/linode/kernels

Lists available Kernels.

Authorizations

Query Parameters

page
Type:
integer >= 1
Default:
1

The page of a collection to return.

page_size
Type:
integer 25..100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Kernel View

GET https://api.linode.com/v4/linode/kernels/{kernelId}

Returns information about a single Kernel.

Authorizations

Path Parameters

kernelId string Required

ID of the Kernel to look up.

Request Samples

Response Samples

Responses